CLI Commands¶

Sovara provides both the unified so-cli interface and the legacy so-record, so-server, and so-config commands.

so-cli¶

Use so-cli for setup, recording, inspection, and reruns.

Setup¶

# Inspect local setup state for the current directory
so-cli status

# Inspect a specific directory or script path
so-cli status --path example_workflows/debug_examples_py/openai

# Create or update the local Sovara user and initialize a project
so-cli init \
  --user-name "Jane Doe" \
  --user-email "jane@example.com" \
  --project-root example_workflows/debug_examples_py/openai \
  --project-name openai-debug

Record¶

# Record a script
so-cli record example.py

# Record with explicit setup overrides
so-cli record \
  --project-root example_workflows/debug_examples_py/openai \
  --project-name openai-debug \
  --user-name "Jane Doe" \
  --user-email "jane@example.com" \
  example_workflows/debug_examples_py/openai/debate.py

so-cli record accepts the same core launch flags as so-record, plus setup overrides:

Option	Description
`--run-name`	Human-readable name for this run
`-m`, `--module`	Run the target as `python -m`
`-u`, `--unbuffered`	Run with unbuffered stdout/stderr
`--user-name`	Create or update the local Sovara user full name
`--user-email`	Create or update the local Sovara user email
`--project-root`	Resolve or create a project for the run
`--project-name`	Create or update the Sovara project name
`--project-description`	Create or update the Sovara project description

In non-interactive environments, prefer so-cli init or explicit setup flags instead of relying on prompts.

Annotation Lists¶

# List queued traces for the current project
so-cli annotations queue --limit 5

# List already annotated reference traces
so-cli annotations annotated --limit 5

# Scope either list to a project ID or unambiguous prefix
so-cli annotations queue --project-id PROJECT_ID_PREFIX --limit 5

so-cli annotations queue returns queued run IDs, summaries, annotation priority, and annotator guidance. so-cli annotations annotated returns labeled reference traces with labels and groundtruth when available.

so-record¶

The legacy single-purpose command for running Python scripts with Sovara analysis.

Basic Usage¶

# Run a script
so-record script.py

# Run a script with arguments
so-record script.py --arg1 value1 --arg2 value2

# Run a module (like you would with python -m mypackage.mymodule)
so-record -m mypackage.mymodule

# Run with environment variables
ENV_VAR=value so-record script.py

Options¶

Option	Description
`--run-name`	Name for this run (for organizing in the UI)
`--user-name`	Create or update the local Sovara user full name
`--user-email`	Create or update the local Sovara user email
`--project-root`	Resolve or create a project for the run
`--project-name`	Create or update the Sovara project name
`--project-description`	Create or update the Sovara project description

Examples¶

# Run a simple script
so-record my_agent.py

# Run a module from a package
so-record -m agents.research_agent

# Run with a custom run name
so-record --run-name "run-v1" my_agent.py

# Pass arguments to your script
so-record my_agent.py --model gpt-4 --temperature 0.7

so-server¶

Manage the Sovara development server.

Commands¶

# Start the server
so-server start

# Stop the server
so-server stop

# Restart the server (useful after code changes)
so-server restart

# Clear all recorded runs and cached LLM calls
so-server clear

# View server logs
so-server logs

# View inference server logs
so-server infer-logs

# Clear all log files
so-server clear-logs

Notes¶

The server automatically starts when you run so-record if it's not already running
If you make changes to server code, run so-server restart to apply them
Log files are stored in ~/.sovara/logs/:
main_server.log - Main server logs
inference_server.log - Inference server and trace-chat logs

Troubleshooting¶

Check if the server process is running:

ps aux | grep 'so_server\|uvicorn'

Check which processes are using the server port:

lsof -i :5959

so-config¶

Configure Sovara settings interactively.

Usage¶

so-config

This launches an interactive configuration wizard that prompts you for:

Project root directory - The root of your Python project
Database URL - Configuration for result caching

When to Use¶

Run so-config when:

Setting up Sovara for a new project
Changing the project root directory
Configuring database settings for caching

Project Root

For some example workflows, you may need to set the project root to the example's directory. Run so-config and set it to the root of the example repo.

Environment Variables¶

Sovara respects the following environment variables:

Core Variables¶

Variable	Description
`SOVARA_RUN_ID`	Current run identifier
`SOVARA_SEED`	Random seed for reproducibility

Server Configuration¶

Variable	Description
`HOST`	Server host (default: `127.0.0.1`)
`PYTHON_PORT`	Server port (default: `5959`)

Path Customization¶

Variable	Description
`SOVARA_HOME`	Base directory for Sovara files (default: `~/.sovara`)
`SOVARA_CONFIG`	Path to config file (default: `~/.sovara/config.yaml`)
`SOVARA_CACHE`	Cache directory (default: `~/.cache/.sovara`)
`SOVARA_LOG_DIR`	Log directory (default: `~/.sovara/logs`)
`SOVARA_DB_PATH`	Database directory (default: `~/.sovara/db`)
`SOVARA_GIT_DIR`	Git versioning directory (default: `~/.sovara/git`)