Reference

Run sovara --help for the command list installed on your machine. Every command and subcommand accepts -h and --help for its exact usage and flags.

usage: sovara <command> [options]

Setup and connectivity

Command	Purpose
`sovara status`	Check the active app-server connection.
`sovara projects`	List projects or fetch one by ID, ID prefix, or exact name.
`sovara setup [--path DIR]`	Install the skill and launch an available coding assistant to instrument a repository.
`sovara onboard [--path DIR]`	Launch benchmark-grounded onboarding for an instrumented agent.
`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.

App commands use the active app-server connection selected in the Sovara desktop app: either Local or a remembered remote connection. For a remote connection, they also use its signed-in desktop session. Switch app-server connections with the selector on the Projects page; the CLI has no separate app-server endpoint setting.

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 in one project.
`sovara tags list --project-id <project>`	List tag names, colors, and IDs usable in run filters.
`sovara probe (<run-id> \| --project-id PROJECT --run-key KEY)`	Inspect run structure and step payloads.
`sovara step-overview (<run-id> \| --project-id PROJECT --run-key KEY) --step <step-ref>`	Summarize one step.
`sovara logs (<run-id> \| --project-id PROJECT --run-key KEY)`	Read captured stdout and stderr.

Project selection for a run is defined by SDK code, not record or the working directory. Commands that target one run accept either its full Sovara UUID or an unambiguous UUID prefix, with no project flag, or its exact SDK run key together with --project-id. Run keys are project-scoped, so the project is required:

sovara probe 4e341aec
sovara probe --project-id <project-id-or-name> --run-key <run-key>

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> --run-key <run-key>
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":"number","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/. Normal Sovara application logs are always archived on macOS, Windows, and Linux. --include-system-logs additionally collects the last 30 minutes of Sovara-related macOS Unified Logs, Windows Application/Defender/Code Integrity/AppLocker events, or Linux systemd journal entries. System-log collection is opt-in because OS logs may contain sensitive machine metadata. It is best-effort, never requests elevated privileges, and writes system/system-log-collection.txt with status=unavailable when the platform source cannot be read.

Step rerun

sovara rerun (<run-id> | --project-id PROJECT --run-key KEY) --step <step-ref> [--disable-lesson-injection] [--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. Reruns perform current lesson retrieval by default; pass --disable-lesson-injection to skip retrieving and injecting new lessons for that rerun.

Replay keys

Command	Purpose
`sovara replay-keys list --project-id PROJECT`	Show masked previews of configured replay keys.
`sovara replay-keys set <provider> --project-id PROJECT --api-key-env ENV_VAR`	Store a provider key from an environment variable.
`sovara replay-keys set <provider> --project-id PROJECT --api-key-stdin`	Store a provider key from stdin.
`sovara replay-keys unset <provider> --project-id PROJECT`	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 --run-key <run-key>
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. The direct annotation commands accept the same two run selector forms as probe. For example:

sovara annotations inspect --project-id <project-id-or-name> --run-key <run-key>

Project issues

Every issue command requires --project-id:

sovara issues list --project-id <project> --status open
sovara issues list --project-id <project> --status closed --view created --query "timeout"
sovara issues get 42 --project-id <project>
sovara issues create --project-id <project> --title "Retry behavior is unclear" --body "See #17."
sovara issues comment 42 --project-id <project> --body "Reproduced in the latest run."
sovara issues close 42 --project-id <project>

Use positive project reference numbers without a leading #. Commands output JSON. Issue reads and comments reject references that resolve to lesson conversations.

Lessons

Every lessons command requires --project-id:

sovara lessons ls [-R] [path] --project-id <project-id-or-name>
sovara lessons get <lesson-id>[,<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>"] [--draft] [(--run-id <run-id-or-prefix> | --run-key <run-key>) --step <step-ref>]
sovara lessons polish <lesson-id> --project-id <project-id-or-name>
sovara lessons retrieve --project-id <project-id-or-name> "<context>"

ls lists the root folder when path is omitted or "". Add -R / --recursive for compact recursive output. get accepts one lesson ID or a comma-separated list. Use --draft on lesson creation to save without validation or activation. Draft creation and --force are mutually exclusive. 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

Project issues

Lessons

​Setup and connectivity

​Local exec server

​Recording and inspection

​Diagnostics

​Step rerun

​Replay keys

​Annotations

​Project issues

​Lessons

Setup and connectivity

Local exec server

Recording and inspection

Diagnostics

Step rerun

Replay keys

Annotations

Project issues

Lessons