Reference

Run sovara --help for the command list installed on your machine.

usage: sovara <command> [options]

Setup and connectivity

Command	Purpose
`sovara status`	Check backend health and the signed-in user.
`sovara projects`	List projects or fetch one by ID, ID prefix, or exact name.
`sovara setup`	Install the skill and launch an available coding assistant in the current directory. Accepts no options.
`sovara install-skill`	Install assistant guidance for Codex, Claude Code, or both.
`sovara update`	Check for or install the latest CLI release.
`sovara exec-server`	Start, health-check, or stop the bundled local exec server.

Local exec server

sovara exec-server start
sovara exec-server stop

start launches the bundled exec server when the configured local endpoint is not healthy. With an explicit --server-url, it only health-checks that endpoint. stop accepts only a local URL, stops the bundled server and its Qdrant sidecar, and succeeds when they are already stopped.

Recording and inspection

Command	Purpose
`sovara record -- <command> [args...]`	Execute a command unchanged and report its SDK-created run.
`sovara runs`	List recorded runs, optionally scoped with `--project-id`.
`sovara tags list --project-id <project>`	List tag names, colors, and IDs usable in run filters.
`sovara probe <run-id>`	Inspect run structure and step payloads.
`sovara step-overview <run-id> --step <step-ref>`	Summarize one step.
`sovara logs <run-id>`	Read captured stdout and stderr.

Project selection for a run is defined by SDK code, not record or the working directory. Project-scoped run listing mirrors the Runs API. It returns the selected page plus distinct_code_versions and custom_metric_columns for discovering discrete filters:

sovara tags list --project-id <project-id-or-name>
sovara runs --project-id <project-id-or-name> --limit 20 --offset 0 --sort timestamp --dir desc
sovara runs --project-id <project-id-or-name> --name eval --run-id 4e341aec
sovara runs --project-id <project-id-or-name> --label up,down --tag-id <tag-id> --code-version <short-sha>
sovara runs --project-id <project-id-or-name> --time-from 2026-07-01T00:00:00Z --latency-min 1.5
sovara runs --project-id <project-id-or-name> --sort metric:quality --metric-filters '{"quality":{"kind":"float","min":0.8}}'

List-valued flags are comma-separated. Multiple --tag-id values are ANDed. --project-id is required for every run list.

Diagnostics

Create a ZIP archive of local service logs and their retained rotations:

sovara diagnostics
sovara diagnostics --output ./sovara-diagnostics.zip
sovara diagnostics --include-system-logs

Without --output, the archive is written under ~/.sovara/diagnostics/. On macOS, --include-system-logs adds the last 30 minutes of Sovara-related Unified Log entries. This is opt-in because OS logs may contain sensitive machine metadata.

Step rerun

sovara rerun <run-id> --step <step-ref> [--set KEY=VALUE] [--set-file KEY=PATH] [--set-json KEY=JSON]

Only keys shown by probe for the selected step can be edited. See Rerun LLM Steps for examples.

Replay keys

Command	Purpose
`sovara replay-keys list`	Show masked previews of configured replay keys.
`sovara replay-keys set <provider> --api-key-env ENV_VAR`	Store a provider key from an environment variable.
`sovara replay-keys set <provider> --api-key-stdin`	Store a provider key from stdin.
`sovara replay-keys unset <provider>`	Remove a provider replay key.

See Replay Keys for provider naming and validation details.

Annotations

sovara annotations list --project-id <project-id-or-name> --status queue
sovara annotations list --project-id <project-id-or-name> --status queue --sort failureScore --dir desc --failure-min 0.5
sovara annotations inspect <run-id>
sovara annotations enqueue <run-id>
sovara annotations set <run-id> --label success
sovara annotations set <run-id> --label failure --groundtruth "<expected outcome>" --steps 4,6.2
sovara annotations remove <run-id>

Annotation list filters include paging, name/run ID, free-text query, time, runtime, code version, and queue-only failure score, novelty score, analysis, and tag filters. Annotated lists additionally accept --label success,failure. The JSON preserves scores, statuses, tags, and distinct_code_versions. annotations inspect prints the complete run-annotation response. The persisted recommendation is under recommendation and includes analysis, scores, statuses, adjudication pairs, closest failure evidence, and most-novel evidence.

Lessons

Every lessons command requires --project-id (or its --proj-id alias):

sovara lessons list --project-id <project-id-or-name>
sovara lessons get <lesson-id> --project-id <project-id-or-name>
sovara lessons create --project-id <project-id-or-name> --title "<title>" --content "<content>" --when-to-use "<retrieval hint>"
sovara lessons polish <lesson-id> --project-id <project-id-or-name>
sovara lessons retrieve --project-id <project-id-or-name> "<context>"

Use --force on lesson commands only when you intentionally want to skip model validation.

Get started

Core workflows

Assistant workflows

Reference

Setup and connectivity

Local exec server

Recording and inspection

Diagnostics

Step rerun

Replay keys

Annotations

Lessons

​Setup and connectivity

​Local exec server

​Recording and inspection

​Diagnostics

​Step rerun

​Replay keys

​Annotations

​Lessons

Setup and connectivity

Local exec server

Recording and inspection

Diagnostics

Step rerun

Replay keys

Annotations

Lessons