Skip to main content
sovara is the terminal interface for Sovara. It is designed for humans and AI coding tools such as Claude Code and Codex. The CLI can check backend connectivity, initialize user and project state, record Python scripts, list projects and runs, inspect trace graphs, read persisted logs, annotate examples, install assistant skill guidance, and manage SovaraDB priors without needing to click through the desktop app. Commands output JSON so coding agents can parse the results reliably.

​
Install the CLI

Install the CLI on macOS or Linux with: 
curl -fsSL https://apps.sovara-labs.com/cli/install.sh | sh
For Windows, download the Windows archive listed in https://apps.sovara-labs.com/cli/latest.json and place sovara.exe on your PATH. Then check that the configured backend is reachable and the current folder has local Sovara setup: 
sovara status
For an on-prem or remote server, set the backend URL once: 
sovara init --server-url http://<server-host>:5959

​
Guided setup

To onboard a project end to end, run sovara setup. It installs the Sovara skill and spawns Claude Code or Codex with a prompt that verifies the desktop app, installs the matching SDK, and records a first run: 
sovara setup
It auto-detects which assistant is on your PATH and prompts you when both are installed. See Claude Code and Codex for the target-specific flags.

​
Basic usage

Initialize project state: 
sovara init \
  --project-root /path/to/project \
  --project-name "Support Agent"
Record a Python script: 
sovara record --run-name smoke-test -- python agent.py
List recent runs: 
sovara runs --project-id <project-id>
Inspect a run: 
sovara probe <run-id> --only-steps
sovara probe <run-id> --step 3
Queue and annotate a run: 
sovara queue-annotation <run-id>
sovara annotate <run-id> --label failure --groundtruth "The expected answer is ..."
Work with SovaraDB priors: 
sovara priors list --project-id <project-id>
sovara priors retrieve "agent receives transient HTTP 429 responses" --project-id <project-id>

​
Command surface

usage: sovara <command> [options]

Commands:
  status             Check the configured Sovara backend and local setup
  init               Configure user/project state through the backend
  projects           List projects or fetch one project
  record             Run a Python command under Sovara recording
  probe              Inspect a recorded run
  step-overview      Show a semantic overview for a run step
  annotate           Mark a run as success or failure
  queue-annotation   Queue a run for annotation evaluation
  logs               Show persisted logs for a run
  runs               List recorded runs
  annotations        List annotation queue or annotated runs
  install-skill      Install Sovara skill guidance
  setup              Install the skill and spawn Codex or Claude Code to onboard
  priors             Manage SovaraDB priors
Next, see the available tools.