CLI reference

This page lists the SOBA Agent v0.6.x CLI surface available from the console.

1. Launch modes

2. Top-level flags

Session and modes

Provider and model

An unqualified model ID stays on the configured default provider. A qualified value such as openrouter/deepseek/deepseek-v4-flash selects openrouter and sends deepseek/deepseek-v4-flash as its model ID.

Limits

Interface and behavior

Sound

Info

3. Proof commands

Proof bundles are persisted in .soba/evidence/*.soba-proof.json after accepted agent finishes. Current proof bundles include a compact evidence index, finish claims, changed files, checks, commands, permission receipts, risks, and review actions. Permission receipts record each executed tool call's trust level, approval kind, approval value, decision, reason, and safer alternatives when SOBA can suggest a least-privilege rewrite; auto means SOBA's trust policy allowed the call without prompting. New receipts also contain proofId, runId, and a SHA-256 integrity.digest. soba verify validates schema and content integrity, supported claim references, command outcomes, mutation ordering, diff completeness, permissions, and secret redaction.

soba prove, soba verify, and soba explain-claim do not start the agent runtime and do not require provider credentials. Their human output is compact by default. --verbose restores technical detail, while JSON schemas and exit codes stay unchanged for automation.

soba verify uses stable policy exits: 0 verified, 1 invalid, 2 partially verified, 3 unverified, and 4 blocked. JSON output includes accepted, outcome, reason, and exitCode. Legacy receipts without integrity metadata remain readable, but are downgraded to partially_verified with reason legacy_unsealed_proof and exit code 2.

4. Project Memory commands

Project Memory lives in .soba/memory/. soba memory doctor inspects the persisted knowledge files and memory capsules without starting the agent runtime. It reports knowledge file counts, estimated token usage, capsule source provenance, stale capsules, missing sources, outside-project source references, and corrupt capsule files.

Exit code is 0 only when memory is healthy. Stale or broken memory returns 1 and writes the report to stderr. For soba memory stale, exit code is 0 only when there are no stale or broken capsules and no memory doctor issues. For soba memory verify, exit code is 0 only when the verification report is verified: true. For soba memory explain, exit code is 0 only when at least one matching capsule is safe to use; stale, broken, or missing matches return 1.

soba memory doctor, soba memory stale, soba memory verify, and soba memory explain do not start the agent runtime and do not require provider credentials.

5. Provider subcommands

The provider registry is managed through the soba provider sub-route.

soba provider add

Supported flags:

--model format:

id[=name][,contextWindow[,maxOutput[,supportsStreaming[,supportsThinking]]]]

Example keyless local provider:

soba provider add ollama \
  --base-url http://localhost:11434/v1 \
  --model llama3.1="Llama 3.1",8192,2048 \
  --set-active

8192,2048 is a gentle starting point for a local model: context window first, max output tokens second. Larger values such as 128000,8192 can put a lot of pressure on memory and make a laptop feel painfully slow.

Limits are optional. For example, --model local-code="Local Code" --metadata-profile vllm lets SOBA fill context/output values from the endpoint when it exposes them. If metadata is absent, SOBA uses conservative assumed values and marks them with ~; pass explicit numbers when the server catalogue is incomplete.

Structured reasoning capabilities and the provider-specific wire transport are declared in a full JSON definition loaded with --from-file. SOBA never sends reasoning fields to an unknown endpoint merely because the model name looks familiar.

5. Practical check commands

soba --version
soba --help
soba prove --last
soba verify --last
soba explain-claim claim_1 --last
soba provider list
soba --no-session --max-agent-iterations 1 "Answer with one word: ok"

For development in the repository:

soba -i --lang en --theme graphite

6. Direct shell in the TUI

In interactive mode, shell commands can be run directly:

!git status --short
!bun test
!!bun run build

! runs the command immediately. !! runs it without adding output to the transcript. If you want the agent to see and analyze the output, ask it to run the command through a normal prompt, which uses the bash tool.

Next

• Providers and models
• Interface and commands
• Configuration