CLI Reference

The CLI

The obs CLI is how you talk to Obsidian . It is not an afterthought bolted onto an API. It is the primary interface — designed to be fast (under 10 milliseconds for most operations), readable as English, and scriptable for automation. Constitution Principle 9 is explicit: only the LLM should be slow.

$ obs [command] [subcommand] [options] [arguments]

Fast:       <10ms for most commands (only LLM is slow)
Intuitive:  Commands read like English
Consistent: Same patterns across all commands
Powerful:   Full control of the entire system
Scriptable: JSON output for automation

Command Categories

The CLI organizes into categories that mirror Obsidian’s architecture. Core commands for status and management. Work commands for the Task Pipeline . Vault commands for knowledge. Instance commands for Agent lifecycle. Config, secrets, plugins, LLM, deployment, chaos testing, and logging — each gets its own command group with consistent patterns.

CORE           WORK            VAULT          INSTANCE
──────         ──────          ──────         ──────
status         hook            search         list
agents         claim           remember       spawn
tasks          done            forget         delegate
               strike          context        escalate
               reject          export

CONFIG         SECRETS         PLUGINS        LLM
──────         ──────          ──────         ──────
show           get             list           providers
validate       set             install        benchmark
reload         rotate          uninstall      cost
edit           list            enable
                               disable

DEPLOY         CHAOS           LOGS
──────         ──────          ──────
staging        test            follow
production     report          audit
rollback       schedule        query
status                         export

Core Commands

obs status

The single command you run when you want to know if everything is fine. It shows environment, version, agent states, task counts, and system health — all in one glance.

# Basic status
obs status

# Detailed metrics
obs status -v

# Watch mode — live updating
obs status -w

# JSON for scripting
obs status --json | jq '.agents.active'

Every flag follows the same pattern across every command: --json for machine output, --verbose for detail, --watch for live updates. Consistency is not a nice-to-have. It is a constitutional requirement.

obs agents

List and manage agents. Filter by type, status, or get detailed info on a specific agent. The lint subcommand validates agent definitions against the configuration schema — because an agent with a malformed config is worse than no agent at all.

obs agents                     # List all active agents
obs agents show researcher     # Detailed agent info
obs agents --status active     # Filter by status
obs agents lint --all          # Validate definitions

obs tasks

The window into the Task Pipeline . List tasks, filter by status, create new ones, cancel or retry failed ones. Every task has an ID, a type, a status, an assigned agent, and a priority. Every task is traceable.

obs tasks                                    # List all
obs tasks --status pending                   # Filter
obs tasks show task_12345                    # Details
obs tasks create --type research --priority high "Research quantum computing"
obs tasks --since 1h                         # Recent tasks

Work Commands

These are the verbs of the system — the commands agents and operators use to move work through the pipeline.

obs hook

Creates a task. The name is deliberate: you are hooking work into the system. Optionally claim it immediately, assign it to a specific agent, attach context files, or set it as a subtask of an existing task. Fractal Delegation starts here.

obs hook "Research the latest AI safety papers"
obs hook --claim "Fix the login bug"
obs hook --priority critical "Security vulnerability assessment"
obs hook --parent task_12345 "Write unit tests for auth module"

obs claim

An agent (or operator) claims a task. This is pull-based work discovery in action — agents find work and take ownership, rather than having work pushed to them by a scheduler. The output tells you exactly how to complete or fail the task.

obs claim task_12347
obs claim task_12347 --note "Starting code review"

obs done and obs strike

Binary outcomes. Work is either done or it isn’t. obs done marks completion with optional output and artifacts. obs strike records failure with a mandatory reason — because failure without explanation is just noise.

obs done task_12347 --output "Approved with minor suggestions"
obs strike task_12349 --reason "External API is down" --retry
obs strike task_12349 --reason "Needs human decision" --escalate

The --escalate flag triggers human review. This is automation with human gates — the system handles what it can, and knows when to ask for help.

Vault Commands

The Vault is Obsidian’s knowledge layer — semantic search, persistent memory, and institutional knowledge that survives across sessions and agent lifetimes.

obs vault search

Semantic search across all stored knowledge. Not keyword matching — meaning matching. Filter by content type, source agent, time range, and similarity threshold.

obs vault search "authentication best practices"
obs vault search --type code "retry logic patterns"
obs vault search --threshold 0.9 "error handling"
obs vault search --since 24h "deployment issues"

obs vault remember

Store knowledge. Any agent can remember. Tags and task associations make retrieval precise. This is how the system learns — not through retraining, but through structured accumulation of operational wisdom.

obs vault remember "Always use parameterized queries to prevent SQL injection"
obs vault remember --file ./research_notes.md --title "AI Safety Research"
obs vault remember --type code --tags "auth,security" "Use bcrypt for password hashing"

Instance Commands

Agent lifecycle management. Spawn, delegate, escalate — the verbs of orchestration.

obs instance spawn

Create agent instances. Spawn one researcher, or three coders, or a custom-configured specialist. Each instance gets its own ID, resource allocation, and lifecycle tracking.

obs instance spawn researcher
obs instance spawn coder --count 3
obs instance spawn researcher --config ./custom_researcher.yaml

obs delegate and obs escalate

Move work between agents or up to human review. Delegation can override priority and add context. Escalation always requires a reason — the system demands accountability for every decision that involves a human.

obs delegate task_12350 researcher
obs delegate task_12350 coder --priority high
obs escalate task_12351 --reason "Requires domain expertise" --notify slack,email

Config, Secrets, and Plugins

Configuration

obs config show displays configuration with optional environment variable resolution. obs config validate checks your config against the schema — with a --fix flag for common issues and a --strict mode that promotes warnings to errors.

Secrets

obs secrets get retrieves secrets through the provider abstraction. obs secrets set stores them. obs secrets rotate triggers rotation. Every access is logged. Every operation respects the Constitutional Compliance rules for secret access control.

obs secrets get api-keys/openai
obs secrets set --provider vault api-keys/new-service "sk-..."
obs secrets rotate api-keys/openai
obs secrets list --provider infisical

Plugins

Install from npm, git, or local paths. Enable and disable without uninstalling. The plugin system is Obsidian’s extensibility mechanism — capabilities are declared, not hard-coded.

obs plugins install @obsidian/plugin-slack
obs plugins install --git https://github.com/acme/custom-plugin.git
obs plugins enable slack-notifications
obs plugins disable slack-notifications

Deployment and Chaos

Deployment

obs deploy staging and obs deploy production handle the deployment pipeline. Production requires the --confirm flag — because deploying to production should require a moment of deliberate intention.

obs deploy staging
obs deploy production --confirm
obs deploy rollback --to v2.3.0
obs deploy status

Chaos Testing

Yes, the CLI has built-in chaos testing. obs chaos test runs failure scenarios. obs chaos schedule sets up recurring chaos tests. This is Constitution Principle 1 operationalized: you do not hope your system survives failure. You prove it.

obs chaos test --scenario agent-failure
obs chaos test --scenario network-partition --duration 5m
obs chaos report --since 7d

Design Philosophy

Every command follows the same contract: predictable flags, JSON output for scripting, exit codes for automation. --json always works. --verbose always adds detail. Human-readable by default, machine-parseable on demand.

This is what Constitution Principle 10 means: powerful and simple aren’t opposites. The CLI gives you full control of a complex multi-agent system through commands that read like English. That is not an accident. That is architecture.