sovara --help for the command list installed on your machine. Every
command and subcommand accepts -h and --help for its exact usage and flags.
Setup and connectivity
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
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
Project selection for a trace is defined by SDK code, not
record or the
working directory.
Use the trace ID shown in Sovara or a unique ID prefix. To use your own
identifier from the SDK, include --project-id:
distinct_code_versions and custom_metric_columns for discovering
discrete filters:
--trace-id filters by a fragment of the trace ID.
List-valued flags are comma-separated. Multiple --tag-id values are ANDed.
--project-id is required for every trace list.
Diagnostics
Create a ZIP archive of local service logs and their retained rotations:--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
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.
Use --proposal ID to preview lessons as if that proposal were merged into current
production, without applying it. Proposal reruns preserve the source step and
return a separate rerun_id with proposal/revision provenance. Merge conflicts
are rejected before replay. This requires editor access and a server supporting
proposal reruns; it cannot be combined with --disable-lesson-injection.
Replay keys
See Replay Keys for provider naming and validation details.
Annotations
--label up,down.
The JSON preserves scores, statuses, tags, and distinct_code_versions.
traces inspect prints the complete trace-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 trace argument as probe. For
example:
Project issues
Every issue command requires--project-id:
#. Commands output
JSON. Issue reads and comments reject references that resolve to lesson
conversations.
Lessons
Every lessons command requires--project-id:
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.
Creation requires a title, content, and --when-to-use. Creation, updates, folder
changes, and deletions save to a proposal. Reuse the returned proposal ID with
--proposal for related edits. Review is advisory; only explicit
lessons proposals apply publishes changes. See Lessons for
revision guards and the complete workflow.
Create a project
Trace tags
Every tag command requires--project-id. Create tags, assign them to a trace, or
remove them:
set replaces the complete tag list. Include every tag you want to keep; an empty
--tag-ids clears it. Deleting a tag removes all its trace assignments. The default
creation color is blue; see the MCP tag reference
for the supported palette.
Automations
Every automation command requires--project-id. Commands return JSON.
--enabled=false is supplied. Use --thinking-level to select a
supported reasoning level (default medium). Every execution starts a fresh
conversation and reuses that automation’s files. The deprecated
--remember-previous-runs flag is accepted but ignored.
Updates change only explicitly supplied options. Mutations fetch the current
revision before applying the change; provide --expected-revision N to require a
specific revision you have already reviewed. A revision conflict requires reading
the automation again before retrying.
List commands support --limit and --cursor; pass the returned next_cursor
to fetch another page. list also accepts --search and --enabled filters.
recent-runs lists executions that have started, while executions also shows
queued work. execution reads the shared result, including output and status.
Saved automations continue running independently of the CLI or MCP connection.
Pause or delete them to stop future scheduled work. Scheduled and immediate
executions consume your organization’s model usage.