CLI 参考

本页列出可以在控制台中使用的 SOBA Agent v0.6.x CLI。

1. 启动模式

2. 顶层标志

会话和模式

Provider 和模型

未限定的 model ID 会继续使用已配置的 default provider。像 openrouter/deepseek/deepseek-v4-flash 这样的限定值会选择 openrouter，并向其发送 model ID deepseek/deepseek-v4-flash。

限制

界面和行为

声音

信息

3. Proof 命令

Agent accepted finish 后，proof bundles 会保存到 .soba/evidence/*.soba-proof.json。 当前 proof bundles 包含紧凑 evidence index、finish claims、changed files、checks、commands、permission receipts、risks 和 review actions。 Permission receipts 会记录每个已执行 tool call 的 trust level、approval kind、approval value、decision、reason，以及 SOBA 能够建议 least-privilege rewrite 时的更安全替代方案；auto 表示 SOBA trust policy 无需提示即可允许该调用。 新 receipts 还包含 proofId、runId 和 SHA-256 integrity.digest。soba verify 会检查 schema 与 content integrity、supported claim 引用、命令 outcomes、mutation 顺序、diff 完整性、permissions 和 secret redaction。

soba prove、soba verify 和 soba explain-claim 不启动 agent runtime，也不需要 provider credentials。 Human output 默认保持紧凑。--verbose 会恢复技术细节，而 JSON schemas 和 exit codes 对自动化保持不变。

soba verify 使用稳定的 policy exits：0 verified、1 invalid、2 partially verified、3 unverified、4 blocked。JSON 输出包含 accepted、outcome、reason 和 exitCode。没有 integrity metadata 的 legacy receipts 仍可读取，但会降级为 partially_verified，reason 为 legacy_unsealed_proof，exit code 为 2。

4. Project Memory 命令

Project Memory 保存在 .soba/memory/。soba memory doctor 会检查 persisted knowledge files 和 memory capsules，而不会启动 agent runtime。 报告包含 knowledge file 数量、估算 token usage、capsule source provenance、stale capsules、缺失 source、指向项目外部的 source，以及损坏的 capsule files。

只有状态为 healthy 时 exit code 才是 0。Stale 或 broken memory 会返回 1，并把报告写入 stderr。 对于 soba memory stale，只有没有 stale 或 broken capsules 且没有 memory doctor issues 时 exit code 才是 0。 对于 soba memory verify，只有 verification report 为 verified: true 时 exit code 才是 0。 对于 soba memory explain，只有找到至少一个可安全使用的 capsule 时 exit code 才是 0；stale、broken 或没有匹配时返回 1。

soba memory doctor、soba memory stale、soba memory verify 和 soba memory explain 不启动 agent runtime，也不需要 provider credentials。

5. Provider 子命令

Provider registry 通过 soba provider 子路由管理。

soba provider add

支持的标志：

--model 格式：

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

keyless 本地 provider 示例：

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

8192,2048 是本地模型更温和的起步值：前者是 context window，后者是最大输出 token。像 128000,8192 这样的大值会明显占用内存，也可能让笔记本变得很慢。

Limits 可以省略。例如，--model local-code="Local Code" --metadata-profile vllm 可以在 endpoint 提供 metadata 时让 SOBA 填充 context/output。若 metadata 不存在，SOBA 会使用保守的推定值并用 ~ 标记；server catalogue 不完整时请显式传入数字。

结构化 reasoning capabilities 和 provider-specific wire transport 通过 --from-file 加载的完整 JSON definition 声明。SOBA 不会仅因为模型名称看起来熟悉，就向未知 endpoint 发送 reasoning fields。

5. 实用检查命令

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"

在仓库中开发时：

soba -i --lang zh --theme graphite

6. TUI 中的 direct shell

在交互模式中，可以直接运行 shell 命令：

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

! 会立即执行命令。!! 会执行命令，但不会把输出写入 transcript。若希望代理看到并分析输出，请用普通 prompt 让它运行命令，这样会使用 bash tool。

下一步

• Provider 与模型
• 界面与命令
• 配置