CLI Reference

SOMA ships 20 commands grouped into seven categories. Every command operates on the vault at .soma/vault/ (override with --vault <path>).

Ingestion

`soma ingest`

Ingest trace files from one or more directories into the vault as L1 archive entries.

soma ingest --traces ./agent-logs --traces ./external-feeds

Flags:

Flag	Required	Default	Description
`--traces <dir>`	Yes (repeatable)	—	Directory containing `.json`, `.jsonl`, or `.md` trace files
`--vault <dir>`	No	`.soma/vault`	Vault directory

Example output:

$ soma ingest --traces ./agent-logs
[soma] Scanning ./agent-logs ...
[soma] Found 47 trace files (32 .json, 12 .jsonl, 3 .md)
[soma] Ingested 128 events -> 128 execution entities (L1)
[soma] Created 6 agent profiles
[soma] Extracted 43 decisions from 12 ExecutionGraphs
[soma] Skipped 4 duplicate traces (by trace_id)
[soma] Done. Vault: 177 entities

The Harvester worker processes each file, creates execution entities in L1, updates or creates agent profiles, and extracts decision entities from any ExecutionGraph objects found in the traces.

`soma run`

Run the full SOMA pipeline: Harvester, Reconciler, Synthesizer, Cartographer, Decay Processor, and report generation.

soma run --provider openrouter --model anthropic/claude-sonnet-4

Flags:

Flag	Required	Default	Description
`--provider <name>`	Yes	—	LLM provider: `openrouter`, `anthropic`, `openai`, `custom`
`--model <model>`	Yes	—	Model identifier for synthesis
`--vault <dir>`	No	`.soma/vault`	Vault directory
`--api-key <key>`	No	env vars	API key (see Configuration)

Example output:

$ soma run --provider openrouter --model anthropic/claude-sonnet-4
[soma] === SOMA Pipeline ===
[soma] Harvester: ingested 0 new events (inbox empty)
[soma] Reconciler: scanned 341 entities, fixed 2 (type coercion), merged 1 duplicate
[soma] Synthesizer: analyzed 88 L1 entries -> 3 new L3 proposals
[soma]   - archetype "retry-heavy-agents" (confidence: 0.82, 6 agents)
[soma]   - insight "fetch-data dominates tool usage" (confidence: 0.71, 4 agents)
[soma]   - policy "cap retries at 3" (confidence: 0.45, 1 agent)
[soma] Cartographer: embedded 12 new entities, discovered 2 archetypes, 0 contradictions
[soma] Decay: expired 4 L2 entries, 0 L3 entries
[soma] Report written to soma-report.json
[soma] Done. L1: 298  L2: 12  L3: 19  L4: 8

`soma pipeline`

Run the full soma.run() pipeline as a one-shot command: harvest inbox → reconcile + L1 dedup → synthesize (L3 proposals + decisions) → auto-promote → drift tracking → cartographer → decay.

soma pipeline --provider openrouter --model google/gemini-2.5-flash

Flags:

Flag	Required	Default	Description
`--provider <name>`	No	—	LLM provider. Without it, only harvest + reconcile + decay run
`--model <model>`	No	—	Model identifier for synthesis
`--vault <dir>`	No	`.soma/vault`	Vault directory
`--api-key <key>`	No	env vars	API key
`--embedding-model <model>`	No	—	Model for cartographer embeddings
`--governance-auto-promote`	No	`false`	Enable auto-promotion of high-confidence L3 proposals

Example output:

$ soma pipeline --provider openrouter --model google/gemini-2.5-flash
═══════════════════════════════════════════════════════
  SOMA PIPELINE — Full Intelligence Run
═══════════════════════════════════════════════════════

  Provider: openrouter / google/gemini-2.5-flash
  Auto-promote: false

── Pipeline Results ──────────────────────────────────

  Harvested:      0
  Reconciled:     540 issues, 0 fixed
  Synthesized:    7
  Auto-promoted:  0
  Mapped:         1
  Decayed:        0
  Drift:          0 tracked, 0 alerts

═══════════════════════════════════════════════════════

Unlike soma run, which builds workers inline, pipeline uses the createSoma() orchestrator — this includes L3 synthesis, decision extraction, conformance drift tracking, and decay processing.

`soma watch`

Continuous mode: watches trace directories, ingests new files each cycle, and optionally runs LLM analysis and the full pipeline on configurable intervals.

soma watch --traces ./agent-logs --provider openrouter --model google/gemini-2.5-flash --pipeline-interval 30

Flags:

Flag	Required	Default	Description
`--traces <dir>`	Yes (repeatable)	—	Directory to watch for new trace files
`--provider <name>`	No	—	LLM provider for analysis and pipeline
`--model <model>`	No	—	Required if `--provider` is set
`--vault <dir>`	No	`.soma/vault`	Vault directory
`--interval <seconds>`	No	`60`	Poll interval between cycles
`--analysis-interval <n>`	No	`10`	Run LLM `analyzeAgents()` every N cycles
`--pipeline-interval <n>`	No	`0` (disabled)	Run full `soma.run()` pipeline every N cycles
`--threshold <n>`	No	`0.3`	Failure rate threshold for guard recommendations

The watch loop runs three tiers of processing:

Every cycle (default: 60s) — scan traces, ingest, reconcile, write report
Every analysis-interval cycles (default: every 10 = ~10min) — LLM agent analysis via analyzeAgents()
Every pipeline-interval cycles (if set, e.g. 30 = ~30min) — full soma.run() pipeline including L3 synthesis, auto-promote, drift tracking, cartographer, and decay

The full pipeline runs asynchronously with a lock guard — if a pipeline is still running when the next interval triggers, it is skipped.

Example output:

$ soma watch --traces ./agent-logs --provider openrouter --model google/gemini-2.5-flash --pipeline-interval 30
═══════════════════════════════════════════════════════
  SOMA WATCH — Continuous Intelligence
═══════════════════════════════════════════════════════

  Trace dirs:   ./agent-logs
  Vault:        .soma/vault
  Poll interval: 60s
  Provider:     openrouter / google/gemini-2.5-flash
  LLM analysis: every 10 cycles
  Full pipeline: every 30 cycles (~30min)

  Starting initial scan...
  [09:55:52 PM] Report written: 12 agents, 316 executions, 167 insights, 66 policies

  Watching... (Ctrl+C to stop)

  [09:57:52 PM] Ingested 1 new events (scanned 182 files)
  [09:57:52 PM] Report written: 13 agents, 317 executions, 167 insights, 66 policies

Reports

`soma report`

Generate and display the intelligence report. Reads vault state and outputs soma-report.json.

soma report --threshold 0.3

Flags:

Flag	Required	Default	Description
`--threshold <n>`	No	`0.3`	Minimum confidence score for included insights
`--vault <dir>`	No	`.soma/vault`	Vault directory

Example output:

$ soma report --threshold 0.5
[soma] === SOMA Intelligence Report ===

Agents (6):
  agent-alpha     | 42 runs | 2 failures | 4.8% failure rate | healthy
  agent-beta      | 31 runs | 0 failures | 0.0% failure rate | healthy
  agent-gamma     | 28 runs | 8 failures | 28.6% failure rate | degraded
  agent-delta     | 15 runs | 1 failure  | 6.7% failure rate | healthy
  agent-epsilon   | 12 runs | 0 failures | 0.0% failure rate | healthy
  agent-zeta      | 9 runs  | 9 failures | 100% failure rate | critical

Insights above 0.5 confidence (4):
  [L4] "API rate limits require backoff" (1.00, canon)
  [L3] "retry-heavy-agents" (0.82, pending)
  [L3] "fetch-data dominates tool usage" (0.71, pending)
  [L3] "agent-gamma fails on large payloads" (0.55, pending)

Policies (2):
  [L4] max-retry-count: enforcing (severity: error)
  [L3] payload-size-limit: draft (severity: warning)

Report written to soma-report.json

Layers

`soma layers status`

Show entry counts per knowledge layer.

soma layers status

Example output:

$ soma layers status
[soma] === Vault Layer Status ===

  L4 Canon              8 entries    (mandatory)
  L3 Emerging          19 entries    (advisory)
  L2 Working Memory    12 entries    (contextual)
  L1 Archive          298 entries    (historical)
  ─────────────────────────────────
  Total               337 entries

`soma layers query`

Query the vault by semantic intent. Routes to the appropriate layer(s) based on the intent.

soma layers query --intent <intent> [--topic <topic>] [--team-id <id>]

Flags:

Flag	Required	Default	Description
`--intent <intent>`	Yes	—	One of: `enforce`, `advise`, `brief`, `route`, `all`
`--topic <topic>`	No	—	Filter results by topic/tag
`--team-id <id>`	No	—	Required for `brief` intent

Intent: `enforce`

Queries L4 canon. Returns mandatory constraints agents must follow.

$ soma layers query --intent enforce
[soma] Querying L4 (canon) — semantic weight: mandatory

  [L4] max-retry-count (policy, enforcing)
       "Agents must not retry more than 3 times per operation"
       Ratified by: ops-lead, 2026-03-18

  [L4] api-backoff-required (policy, enforcing)
       "All agents must implement exponential backoff on 429 responses"
       Ratified by: platform-eng, 2026-03-15

Intent: `advise`

Queries L3 emerging knowledge. Returns soft guidance with confidence scores.

$ soma layers query --intent advise
[soma] Querying L3 (emerging) — semantic weight: advisory

  [L3] retry-heavy-agents (archetype, confidence: 0.82)
       "6 agents show excessive retry patterns; consider circuit breakers"

  [L3] fetch-data-dominance (insight, confidence: 0.71)
       "fetch-data is the most-used tool across 4 agents (78% of calls)"

  [L3] payload-size-limit (policy, confidence: 0.55, draft)
       "Large payloads (>1MB) correlate with agent-gamma failures"

Intent: `brief`

Queries L2 working memory. Requires --team-id to scope results to a team.

$ soma layers query --intent brief --team-id platform
[soma] Querying L2 (working memory) — semantic weight: contextual

  [L2] platform-deploy-freeze (constraint, team: platform)
       "Deploy freeze active until 2026-03-22 for Q1 release"
       Expires: 2026-03-28

  [L2] platform-oncall-rotation (context, team: platform)
       "Current oncall: alice (primary), bob (secondary)"
       Expires: 2026-04-01

Without --team-id, the brief intent returns an error:

$ soma layers query --intent brief
[soma] Error: --team-id is required for 'brief' intent (L2 is team-scoped)

Intent: `route`

Queries L1 archive. Returns historical raw traces and decayed entries.

$ soma layers query --intent route --topic "agent-gamma"
[soma] Querying L1 (archive) — semantic weight: historical

  [L1] exec-agent-gamma-20260320-001 (execution, failed)
       Duration: 45s, error: "payload too large"

  [L1] exec-agent-gamma-20260319-003 (execution, completed)
       Duration: 12s, tools: fetch-data, transform

  [L1] decision-tool-choice-fetch-data-agent-gamma (decision, active)
       tool_choice: fetch-data, outcome: completed

Intent: `all`

Returns stratified results from all four layers, each tagged with source layer and semantic weight.

$ soma layers query --intent all --topic "retry"
[soma] Querying all layers (stratified)

  [L4/mandatory]   max-retry-count — "Agents must not retry more than 3 times"
  [L3/advisory]    retry-heavy-agents — "6 agents show excessive retry patterns" (0.82)
  [L1/historical]  decision-retry-agent-alpha-exec-091 — retry count: 4, outcome: failed
  [L1/historical]  decision-retry-agent-beta-exec-044 — retry count: 2, outcome: completed

Governance

`soma governance list`

List all pending L3 proposals awaiting human review, sorted by confidence descending.

$ soma governance list
[soma] === Pending Governance Proposals ===

  ID                          Type        Confidence  Evidence
  retry-heavy-agents          archetype   0.82        14 traces from 6 agents
  fetch-data-dominance        insight     0.71        9 traces from 4 agents
  payload-size-limit          policy      0.55        5 traces from 1 agent
  stale-cache-pattern         insight     0.44        3 traces from 2 agents

  4 proposals pending review

`soma governance show`

Inspect a specific proposal with its full evidence chain.

$ soma governance show --id retry-heavy-agents
[soma] === Proposal: retry-heavy-agents ===

  Type:       archetype
  Layer:      L3 (emerging)
  Status:     pending
  Confidence: 0.82
  Created:    2026-03-20T14:32:09.000Z

  Summary:
    6 agents exhibit retry counts above threshold. Pattern suggests
    missing circuit breaker logic. Agents: alpha, beta, gamma, delta,
    epsilon, zeta.

  Evidence chain (14 entries):
    [L1] decision-retry-agent-alpha-exec-091  (retry count: 4, failed)
    [L1] decision-retry-agent-alpha-exec-088  (retry count: 3, completed)
    [L1] decision-retry-agent-beta-exec-044   (retry count: 5, failed)
    [L1] decision-retry-agent-gamma-exec-031  (retry count: 4, failed)
    ... (10 more)

`soma governance promote`

Promote an L3 proposal to L4 canon. Creates a new L4 entry and marks the L3 as promoted.

$ soma governance promote --id retry-heavy-agents
[soma] Promoting retry-heavy-agents to L4 canon...
[soma] Created L4 entry: canon-retry-heavy-agents
[soma]   ratified_by: cli-user
[soma]   ratified_at: 2026-03-21T09:15:00.000Z
[soma]   origin_l3_id: retry-heavy-agents
[soma] L3 entry marked as 'promoted'
[soma] Done. L4 now has 9 entries.

`soma governance reject`

Reject an L3 proposal. The entry stays in L3 with status rejected and never decays.

$ soma governance reject --id stale-cache-pattern --reason "Insufficient evidence — only 2 agents, need broader validation"
[soma] Rejected stale-cache-pattern
[soma]   reason: "Insufficient evidence — only 2 agents, need broader validation"
[soma]   rejected_by: cli-user
[soma]   rejected_at: 2026-03-21T09:17:00.000Z
[soma] Entry will not decay.

Decay

`soma decay status`

Show entries approaching their expiry date across L2 and L3.

$ soma decay status
[soma] === Decay Status ===

  Expiring within 7 days:
    [L2] platform-deploy-freeze          expires 2026-03-28  (7 days)
    [L3] fetch-data-dominance            expires 2026-04-02  (12 days)

  Recently decayed (moved to L1):
    [L1] decayed-team-alpha-sprint-ctx   decayed_from: working   2026-03-19
    [L1] decayed-cache-invalidation      decayed_from: emerging  2026-03-17

  Layer decay config:
    L2 default: 14 days
    L3 default: 90 days
    Team overrides: { "platform": 21 }

  L1 and L4 entries never decay.
  Promoted/rejected L3 entries never decay.

Migration

`soma migrate-layers`

Migrate a flat (pre-four-layer) vault to the four-layer model. Non-destructive and idempotent.

soma migrate-layers --vault .soma/vault

Flags:

Flag	Required	Default	Description
`--vault <dir>`	No	`.soma/vault`	Vault directory to migrate

Example output:

$ soma migrate-layers
[soma] Scanning vault for unmigrated entities...
[soma] Found 234 entities without layer field
[soma] Migrating...
[soma]   Added layer: 'archive', source_worker: 'migration' to 234 entities
[soma] Skipped 103 entities (already have layer field)
[soma] Migration complete. All entities are now in L1 (archive).
[soma] Use 'soma governance promote' to elevate valuable entries to L4.

All migrated entities start in L1. The migration only adds layer and source_worker fields — it never modifies existing data. Re-running the command skips already-migrated entities.

Ops Intelligence

`soma efficiency`

Analyze per-run token costs with wasteful loop detection. Scans trace files and calls getEfficiency() from the ops-intel module.

soma efficiency [--traces <dir>] [--vault .soma/vault]

Flags:

Flag	Required	Default	Description
`--traces <dir>`	No (repeatable)	Auto-discovered	Trace directories to analyze
`--vault <dir>`	No	`.soma/vault`	Vault directory

Example output:

═══════════════════════════════════════════════════════
  SOMA EFFICIENCY — Cost Analysis
═══════════════════════════════════════════════════════

  Runs analyzed:   83
  Data coverage:   42%

── Aggregate Stats ───────────────────────────────────
  Mean cost/node:   120
  Median cost/node: 95
  P95 cost/node:    340

── Wasteful Patterns ─────────────────────────────────
  ⚠ Retry loop: fetch-data repeated 5x in agent-gamma (1,200 tokens wasted)

── Top Runs by Cost ──────────────────────────────────
  Agent                           Nodes     Cost  Cost/Node
  ────────────────────────────── ────── ──────── ──────────
  agent-alpha                        12     1440        120
  agent-beta                          8      760         95

`soma drift`

Show conformance drift trend for agents. Reads conformance-history.json (generated by soma pipeline) and calls detectDrift().

soma drift [--agent <agentId>] [--vault .soma/vault]

Without --agent, lists all agents with history data. With --agent, shows the drift report.

Flags:

Flag	Required	Default	Description
`--agent <id>`	No	—	Agent to analyze (lists all if omitted)
`--vault <dir>`	No	`.soma/vault`	Vault directory

Example output:

═══════════════════════════════════════════════════════
  SOMA DRIFT — Conformance Trend
═══════════════════════════════════════════════════════

  Agent:       soma-harvester
  Status:      degrading
  Data points: 24
  Window:      24
  Slope:       -0.003200/run
  R²:          0.4500

  ⚠ ALERT: soma-harvester conformance is degrading (slope: -0.0032, R²: 0.45)

`soma receipt`

Print a formatted run receipt for a trace file. Calls toReceipt() and formatReceipt() from agentflow-core.

soma receipt --trace <filename> [--vault .soma/vault]

Flags:

Flag	Required	Default	Description
`--trace <file>`	Yes	—	Trace file path or name (searches common directories)
`--vault <dir>`	No	`.soma/vault`	Vault directory

Example output:

=== Run Receipt ===
Run:      node_001
Agent:    soma-cartographer
Status:   success
Duration: 484ms

Summary: 2 attempted, 0 succeeded, 0 failed, 0 skipped

  # | Step              | Type  | Status    |   Duration |   Tokens
---|-------------------|-------|-----------|------------|----------
  1 | soma-cartographer | agent | success   |      484ms |        —
  2 | llm-call:cluster  | tool  | success   |      484ms |        —

Total token cost: no cost data

`soma decisions`

Show the step-by-step decision chain for a trace or session file. Each decision shows the action taken, reasoning (why), tool used, outcome, and duration.

soma decisions --trace <filename> [--vault .soma/vault]

Flags:

Flag	Required	Default	Description
`--trace <file>`	Yes	—	Trace file path (JSON or JSONL session)
`--vault <dir>`	No	`.soma/vault`	Vault directory

Example output:

═══════════════════════════════════════════════════════
  SOMA DECISIONS — Decision Chain
═══════════════════════════════════════════════════════

  Decisions: 27
  Pattern:   exec:himalaya→process:poll[2]→exec:himalaya[6]→write:inbox[5]→exec:himalaya[5]

  OK: 27  Failed: 0  Skipped: 0

    1. ✔ exec:himalaya
       WHY: I'll process personal emails. Fetching unprocessed...
       OUT: 5 emails returned
    2. ✔ process:poll
       OUT: IMAP connection established
    3. ✔ exec:himalaya
       WHY: Let me read each email body...

Supports both AgentFlow JSON traces (extracts from tool nodes) and session JSONL files (extracts from toolCall/toolResult pairs with reasoning from thinking blocks).

`soma divergence`

Compare decision patterns across agents to find where failing agents make different choices than successful ones.

soma divergence [--vault .soma/vault]

Example output:

═══════════════════════════════════════════════════════
  SOMA DIVERGENCE — Cross-Agent Decision Comparison
═══════════════════════════════════════════════════════

  Agents with decision data: 4

  Agent                              Success  Patterns  Actions
  ─────────────────────────────────── ──────── ───────── ────────
  personal-email-processor              96%         8       12
  finance-email-processor               83%         6        9
  newsletter-digest-daily               40%         5        7
  daily-activity-digest                 39%         4        6

── Divergence Detected ───────────────────────────────

  newsletter-digest-daily diverges from personal-email-processor
    personal-email-processor uses: exec:himalaya, write:inbox
    newsletter-digest-daily uses instead: exec:node, exec:spawn

Requires execution entities with decision data (populated by the harvester during ingestion).

`soma briefing`

Print a full agent health briefing — operational intelligence synthesized from all SOMA data for a specific agent.

soma briefing --agent <agentId> [--vault .soma/vault]

Flags:

Flag	Required	Default	Description
`--agent <id>`	Yes	—	Agent to brief
`--vault <dir>`	No	`.soma/vault`	Vault directory

Example output:

═══════════════════════════════════════════════════════
  SOMA BRIEFING — soma-harvester
═══════════════════════════════════════════════════════

  ✔ HEALTHY — 7.1% failure rate (4/56)

── Intelligence (105 items) ─────────────────────────

  DECISION (27):
    Define a maximum acceptable failure rate
    Benchmark against personal-email-processor
    ... and 25 more

  INSIGHT (41):
    Agents with highest failure rates also have high run counts
    ... and 40 more

  CONSTRAINT (16):
    Perfect reliability only observed in low-run agents
    ... and 15 more

── Peer Comparison ───────────────────────────────────

  soma-cartographer              ████████████████████ 100%
  soma-harvester                 ██████████████████░░  93% ◀
  openclaw:finance-email-proc    ████████████████░░░░  83%
  openclaw:newsletter-digest     ████████░░░░░░░░░░░░  40%

`soma causal`

Show cross-agent knowledge flow — which agents' data contributed to which SOMA recommendations.

soma causal [--vault .soma/vault]

Example output:

═══════════════════════════════════════════════════════
  SOMA CAUSAL — Cross-Agent Knowledge Flow
═══════════════════════════════════════════════════════

  12 cross-agent insights across 4 agent pairs

── personal-email-processor ↔ newsletter-digest-daily (5 insights) ──

  Decision divergence: newsletter-digest vs personal-email-processor
    newsletter-digest (40% overall) uses exec:node (40% success).
    personal-email-processor (96% overall) uses exec:himalaya (96% success).
    tags: divergence, actionable

  ...

  SOMA recommends reviewing these cross-agent patterns.
  Use `soma briefing --agent <id>` for per-agent detail.

Ingestion​

soma ingest​

soma run​

soma pipeline​

soma watch​

Reports​

soma report​

Layers​

soma layers status​

soma layers query​

Intent: enforce​

Intent: advise​

Intent: brief​

Intent: route​

Intent: all​

Governance​

soma governance list​

soma governance show​

soma governance promote​

soma governance reject​

Decay​

soma decay status​

Migration​

soma migrate-layers​

Ops Intelligence​

soma efficiency​

soma drift​

soma receipt​

soma decisions​

soma divergence​

soma briefing​

soma causal​

Ingestion

`soma ingest`

`soma run`

`soma pipeline`

`soma watch`

Reports

`soma report`

Layers

`soma layers status`

`soma layers query`

Intent: `enforce`

Intent: `advise`

Intent: `brief`

Intent: `route`

Intent: `all`

Governance

`soma governance list`

`soma governance show`

`soma governance promote`

`soma governance reject`

Decay

`soma decay status`

Migration

`soma migrate-layers`

Ops Intelligence

`soma efficiency`

`soma drift`

`soma receipt`

`soma decisions`

`soma divergence`

`soma briefing`

`soma causal`