Skip to main content
Codex can use the Sovara CLI to inspect runs, read logs, annotate outcomes, and work with priors from the terminal. This is useful when Codex is debugging an agent and needs structured run data instead of screenshots or copied logs.

​
Guided setup

The fastest way to get started is sovara setup. It installs the Sovara skill and spawns Codex with an onboarding prompt that verifies the desktop app, installs the matching SDK for your project, and records a first run: 
sovara setup --target codex
By default the skill is installed globally to ~/.agents/skills/sovara, so it is available in every project. To scope it to one project instead, use --level project: 
sovara setup --target codex --level project --project-dir /path/to/project
If only Codex is on your PATH, --target is optional — sovara setup auto-detects it. When both Codex and Claude Code are installed, it prompts you to choose, or you can pass --target codex to skip the prompt. Use --dry-run to print what would happen (resolved binary, skill path, and the kickoff prompt) without spawning anything: 
sovara setup --target codex --dry-run

​
Use Codex with Sovara

Install the CLI and make sure the backend is reachable: 
curl -fsSL https://apps.sovara-labs.com/cli/install.sh | sh
sovara status
The most useful requests are operational and trace-focused: 
How can I use Sovara from this repo?
For a concrete task, ask: 
Use the Sovara CLI to list the latest runs for this project.

Use Sovara to inspect why the latest run failed.

Use SovaraDB to check whether there is an existing prior for this failure.
Codex will typically start with: 
sovara status
sovara projects
sovara runs --project-id <project-id>
Then it can inspect a selected run: 
sovara probe <run-id> --only-steps
sovara probe <run-id> --step <step-id>
sovara logs <run-id> --tail 100
If Codex needs to create a fresh run, ask it to use: 
sovara record --run-name codex-debug -- python agent.py
To install or refresh project-local skill guidance for Codex: 
sovara install-skill --target codex --level project --project-dir /path/to/project