Skip to main content
sovara is organized around the work an assistant needs to do: check the backend, initialize local state, find projects, record runs, inspect traces, annotate outcomes, read logs, install shared skill guidance, and work with priors.

​
Setup

CommandUse it for
statusCheck whether the configured Sovara backend is reachable and the current folder has local setup.
initPersist the server URL and configure project state through the backend.
projectsList visible projects or fetch one project by ID or unambiguous prefix.
install-skillInstall the shared Sovara skill for Codex, Claude Code, or both.
setupInstall the skill and spawn Codex or Claude Code with an onboarding prompt.
Typical flow: 
sovara status
sovara init \
  --server-url http://127.0.0.1:5959 \
  --project-root /path/to/project \
  --project-name "Support Agent"
sovara projects
sovara install-skill --target both
To onboard a project interactively instead, run sovara setup — it installs the skill and hands off to your coding assistant. See Claude Code and Codex.

​
Recording and listing runs

CommandUse it for
recordStart a Python script through Sovara recording and return the run_id.
runsList runs, optionally filtered by range, status, regex, or project ID.
Use record when an assistant needs to create a new run from the terminal: 
sovara record --run-name smoke-test -- python path/to/script.py
Use runs to find a recent execution: 
sovara runs --project-id <project-id> --status finished --range :20

​
Inspecting traces

CommandUse it for
probeQuery run metadata, graph structure, node input/output, or specific steps.
step-overviewAsk Sovara for a semantic overview of one graph step.
logsRead persisted run logs with optional grep, tail, context, and line numbers.
The usual inspection path is: 
sovara probe <run-id> --only-steps
sovara probe <run-id> --step 3
sovara step-overview <run-id> --step 3
sovara logs <run-id> --tail 100

​
Annotation

CommandUse it for
queue-annotationAsk Sovara to evaluate a run and add the resulting candidate to the annotation queue.
annotateMark a run as success or failure. Failure labels require ground truth.
annotationsList runs waiting for annotation or runs that are already annotated.
Examples: 
sovara queue-annotation <run-id>
sovara annotate <run-id> --label failure --groundtruth "The expected answer is ..."
sovara annotations queue --project-id <project-id>
sovara annotations annotated --project-id <project-id>

​
Priors

priors contains the SovaraDB command group. It is useful when an assistant needs to inspect or manage priors without opening the desktop app. Common subcommands include:
SubcommandUse it for
list, getRead priors.
create, update, deleteManage prior records.
polishImprove prior wording without changing the original automatically.
query, retrieveFetch priors by folder or retrieval context.
ls, mkdir, mv, cp, rmManage SovaraDB folders and prior placement.
rebalance, restructureMaintain or propose taxonomy changes.
Example: 
sovara priors list --project-id <project-id>
sovara priors retrieve "agent receives intermittent HTTP 429 responses" --project-id <project-id>
For the concepts behind priors, start with What are priors?.