> ## Documentation Index > Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Reference > CLI command reference for common Sovara workflows. Run `sovara --help` for the command list installed on your machine. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} usage: sovara [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 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 -- [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 ` | List tag names, colors, and IDs usable in run filters. | | `sovara probe ` | Inspect run structure and step payloads. | | `sovara step-overview --step ` | Summarize one step. | | `sovara logs ` | 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sovara tags list --project-id sovara runs --project-id --limit 20 --offset 0 --sort timestamp --dir desc sovara runs --project-id --name eval --run-id 4e341aec sovara runs --project-id --label up,down --tag-id --code-version sovara runs --project-id --time-from 2026-07-01T00:00:00Z --latency-min 1.5 sovara runs --project-id --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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} sovara rerun --step [--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](/cli/rerun-steps) for examples. ## Replay keys | Command | Purpose | | --------------------------------------------------------- | -------------------------------------------------- | | `sovara replay-keys list` | Show masked previews of configured replay keys. | | `sovara replay-keys set --api-key-env ENV_VAR` | Store a provider key from an environment variable. | | `sovara replay-keys set --api-key-stdin` | Store a provider key from stdin. | | `sovara replay-keys unset ` | Remove a provider replay key. | See [Replay Keys](/cli/replay-keys) for provider naming and validation details. ## Annotations ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sovara annotations list --project-id --status queue sovara annotations list --project-id --status queue --sort failureScore --dir desc --failure-min 0.5 sovara annotations inspect sovara annotations enqueue sovara annotations set --label success sovara annotations set --label failure --groundtruth "" --steps 4,6.2 sovara annotations remove ``` 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): ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sovara lessons list --project-id sovara lessons get --project-id sovara lessons create --project-id --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.