CLI Commands Reference

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/index.ts
• src/commands/registry.ts
• src/commands/command-names.ts
• src/commands/command-dispatch.ts
• src/agents/architect.ts
• tests/unit/commands/build-help-text.test.ts

The opencode-swarm CLI provides a robust interface for managing agent swarms, project plans, and knowledge stores. Commands are primarily accessed via the /swarm prefix within a session or through the standalone binary using bunx opencode-swarm run <command>.

The system uses a centralized registry to define command behavior, categories, and aliases, ensuring consistency between chat-mediated interactions and direct CLI execution. Some read-only commands are routed through a specialized swarm_command tool, while state-changing operations are handled by the orchestrator.
Sources: src/commands/index.ts:114-118, src/commands/registry.ts:167-172

Command Architecture and Dispatch

The command system is built around a centralized COMMAND_REGISTRY that maps command strings to handlers and metadata. The dispatch logic handles tokenization, alias resolution, and routing.

Command Resolution Logic

When a command is issued, the system attempts to resolve it using a two-tier approach:

1. Compound Match: It first checks if the first two tokens form a compound command (e.g., config doctor).
2. Single Match: If no compound match is found, it falls back to the first token as the command key.

The diagram shows the logic flow for resolving a user command into a registry entry.
Sources: src/commands/registry.ts:511-544, src/commands/command-dispatch.ts

Dispatch Modes

Commands are categorized by how they are executed:

• Tool-Mediated: Read-only commands (e.g., status, show-plan) are routed via the swarm_command tool if the active agent supports it.
• Chat-Mediated: State-changing or unsupported commands are handled directly by the orchestrator or through the CLI fallback.
• CLI-Only: Certain administrative commands must be run via the CLI to ensure canonical output and state protection.
  Sources: src/commands/index.ts:116-118, src/commands/registry.ts:145-151

Core Commands

Core commands manage the lifecycle and visibility of the swarm project.

Command	Description	Category
status	Shows the current swarm state, including active phase and tasks.	core
show-plan	Displays the current .swarm/plan.md. Can be filtered by phase number.	core
agents	Lists all registered agents in the current swarm configuration.	core
finalize	Idempotent terminal finalization: archives evidence, cleans state, and aligns git.	core
handoff	Generates handoff.md with a session snapshot for model switching.	core

Sources: src/commands/registry.ts:175-188, src/commands/registry.ts:285-300, src/commands/registry.ts:360-365

Finalization Workflow

The finalize command (aliased as close) executes a 4-stage process:

1. Retrospectives: Writes retrospectives for in-progress phases.
2. Archiving: Creates a timestamped bundle of artifacts and evidence.
3. Cleaning: Removes active-state files.
4. Alignment: Performs a safe git fast-forward to main.
   Sources: src/commands/registry.ts:289-295

Diagnostics and Health

Diagnostics commands are used to verify the integrity of the swarm's configuration and environment.

Command Health Check

The /swarm diagnose command runs a health check on the swarm state, while preflight executes automation checks. The system also includes a "Doctor" utility:

• config doctor: Validates the resolved configuration and environment.
• doctor tools: Runs a coherence check on tool registrations to ensure agents have access to their assigned tools.
  Sources: src/commands/registry.ts:211-230

Similarity and Suggestions

If an invalid command is typed, the system uses Levenshtein distance to find similar commands and suggest them to the user.
Sources: src/commands/registry.ts:51-105

Knowledge and Memory Management

Swarm knowledge is persistent across sessions and is managed through specialized subcommands.

Subcommand	Action
knowledge list	Lists all current knowledge entries.
knowledge migrate	One-time migration from legacy SME cache to .swarm/knowledge.jsonl.
knowledge quarantine	Moves an entry to quarantine by ID with a specified reason.
knowledge restore	Restores a quarantined entry back to the active store.
memory status	Displays the provider, JSONL, and SQLite migration status.

Sources: src/commands/registry.ts:403-433, src/commands/registry.ts:443-448

Agent-Specific Modes

Certain commands trigger high-level orchestrator modes that utilize specific agent workflows.

Advanced Analysis and Spec Writing

• brainstorm: Triggers a seven-phase discovery workflow (CONTEXT SCAN to TRANSITION) to define requirements before plan creation.
• council: Convenes a multi-model council (Generalist, Skeptic, Domain Expert) for structured deliberation.
• deep-dive: Launches a read-only audit with parallel explorers and dual reviewers.
• pr-review: Executes a structured PR review with 6 parallel lanes (Security, Performance, etc.).
  Sources: src/commands/registry.ts:327-353, src/agents/architect.ts:634-644

UI Design Integration

When a UI-related task is detected, the designer agent can be invoked to produce a code scaffold before implementation. This is gated by the ui_review configuration.
Sources: src/agents/architect.ts:1141-1158

Configuration and Overrides

Feature	Description
concurrency	Manages runtime overrides for task concurrency (Presets: min, medium, max).
turbo	Toggles between "lean" (parallel lanes) and "standard" (skip QA gates) strategies.
full-auto	Enables autonomous execution without confirmation prompts.
qa-gates	Displays or overrides the QA gate profile (e.g., enabling test_engineer or sast_enabled).

Sources: src/commands/registry.ts:308-321, src/commands/registry.ts:366-391, src/commands/registry.ts:392-401

Conclusion

The CLI command system acts as the primary steering mechanism for the swarm. By separating read-only discovery from destructive state changes and providing clear categories for diagnostics and knowledge management, it maintains project integrity while allowing for flexible agent orchestration. All commands are strictly defined in src/commands/registry.ts and exported for use in both chat and CLI environments.