CLI commands

This page documents the main Horus CLI surface. All commands, options, and examples below are sourced from horus --help and horus <command> --help. For the most authoritative version, run those commands in your terminal.

Setup and project commands

horus doctor

Check local readiness: CLI version, git root, .horus config, and source-intelligence setup.

horus doctor
horus doctor --json
horus doctor --config ./horus.config.js

Options: -c, --config <path>, --json

horus init

Initialize a project in one command. horus init (1) runs advisory prerequisite checks — source-intelligence backend presence/version — printed with fix-it hints but never gating the exit code; (2) writes a local .horus/config.json and registers the repo in the global registry at ~/.horus/registry.json (skipped if the repo is already configured); (3) starts or reuses the source-intelligence host; (4) indexes the code and stitches the queue map (producer → queue → worker edges); (5) refreshes the local project-knowledge snapshot. Re-running it is idempotent: it reuses a healthy host and refreshes the index.

horus init
horus init --env staging
horus init --source http://127.0.0.1:8420
horus init --changed --fast
horus init --reindex

Options: --env <name> (default production), --source <url> (record an external, already-running host verbatim and skip the local spawn and index), --path <dir>, -c, --config <path>, --full (full knowledge snapshot, the default), --changed (refresh the project-knowledge snapshot for changed files only — safe as a pre-push hook; does NOT reanalyze the source graph), --fast (speed hint with --changed), --reindex (force a full source re-analysis: stop the host, wipe .horus/source, and rebuild — the way to purge stale graph edges after a backend update), --import-kb <path>. The project name is the repo directory basename; edit .horus/config.json to rename.

Degradation: if the source-intelligence backend is not installed, init still writes and registers the config, skips indexing with an install hint, and exits 0 — investigations then run in degraded, runtime-only mode. If the backend is installed but analyze or host startup fails, init exits 1.

horus readiness

Summarize release/demo readiness: DB, source intelligence, connectors, and local config.

horus readiness
horus readiness --config ./horus.config.js

Options: -c, --config <path>, --ai, --ai-model <model>

Connector and host commands

horus connect <type>

Add or update a connector (elasticsearch, mongodb, postgres, sentry, axiom, shopify, grafana, redis, ai) in .horus/config.json. Run with no flags for an interactive prompt — axiom walks you through token, region, and a live dataset picker.

horus connect elasticsearch --index-pattern 'my-service-prod-*' --service my-service-prod
horus connect mongodb --database my_db --collections users,orders
horus connect postgres --url postgres://:password@host:5432/my_db --tables orders,jobs
horus connect redis --url redis://:password@host:6379
horus connect grafana --dashboard abc123
horus connect sentry --org my-org --sentry-project my-project --auth-token $SENTRY_AUTH_TOKEN
horus connect axiom --token $AXIOM_TOKEN --dataset my-logs

Options: --env <name>, --provider <name>, --api-key <key>, --model <id>, --url <url>, --username <user>, --password <pass>, --index-pattern <pattern>, --service <name>, --database <name>, --collections <list>, --schema <name> (postgres, default public), --tables <list> (postgres allowlist), --dashboard <uid>, --token <token> (axiom), --dataset <name> (axiom), --auth-token <token> (sentry), --org <slug> (sentry), --sentry-project <slug> (sentry project slug — provider domain data, not Horus project targeting), --store <name> (shopify subdomain), --api-version <ver> (shopify, e.g. 2025-10), --access-id <id> (shopify client_id — omit for a static token), --secret <secret> (shopify client_secret or static token, encrypted at rest), --db <spec>, --bullmq-prefix <prefix>, --no-scan-dbs, --no-test

horus stop

Stop the source-intelligence host for the current repo, or every host with --all.

horus stop
horus stop --all

Options: --all

horus hosts

List registered source-intelligence hosts and their live status (port, repo, running/stopped). Each entry is reconciled against the live process behind it (an HTTP health probe plus a pid-liveness fallback), so stale registry rows do not masquerade as running hosts, and orphaned hosts that no registered repo owns are flagged. Pass --reap to stop those orphans.

horus hosts
horus hosts --reap

Options: --reap

horus status

Show config, provider health, and project/environment matrix.

horus status
horus status --env production
horus status --json

Options: -c, --config <path>, --env <name>, --json

Investigation commands

horus investigate <hint>

Run a deterministic investigation for an incident hint. This is the headline command.

horus investigate "checkout latency spike"
horus investigate --env production "checkout timeout"
horus investigate --ai "payment failures"
horus investigate --format json "queue backlog"

Options: -c, --config <path>, --env <name>, --repo <name> (repository WITHIN the loaded config), --scope <path>, --since <ref>, --logs-since <dur>, --timeout <sec>, --service <name>, --shopify-query <q> (Admin GraphQL query as evidence: @file, - for stdin, or a raw string; repeatable), --shopify-variables <json> (variables as @file or inline JSON, applied to every --shopify-query), --json, --format <fmt>, --full (with --json/--format json: the uncapped raw report; JSON is compact by default), --ai, --ai-model <model>

Horus classifies the hint before it runs and adapts. A live symptom ("latency spike", "timeout") or a --since diff is treated as an incident — full runtime evidence, regression hypotheses, and confidence ceilings all apply. A structural hint ("what depends on X", "is X isolated") is treated as source-impact — a structural answer where runtime evidence is irrelevant and is suppressed. The report then ends with a Suggested next block of deterministic, advisory commands (for example horus blast-radius <symbol> for a source-impact hint, or horus search <hint> when no symbol matched). Horus suggests; it never runs them for you. See Self-routing below.

horus packet <hint|savedId>

Build a compact, honesty-framed briefing for a coding agent's context window — from a fresh hint or a saved investigation id. See the Agent packet page for the full format.

horus packet "checkout latency spike"
horus packet "queue backlog" --for claude --json
horus packet <savedId> --json

Options: -c, --config <path>, --env <name>, --scope <path>, --service <name>, --since <ref>, --timeout <sec>, --for <agent>, --json

horus investigations

List recent investigations to get their IDs for replay or postmortem.

horus investigations
horus investigations -n 20

Options: -c, --config <path>, -n, --limit <n>, --json

horus replay <id>

Re-render a saved investigation from your local store without re-querying your systems.

horus replay <id>
horus replay <id> --format markdown
horus replay <id> --ai

Options: -c, --config <path>, --format <fmt>, --ai, --ai-model <model>, --refresh-ai

horus postmortem <id>

Draft an editable incident postmortem from a saved investigation.

horus postmortem <id>
horus postmortem <id> --output ./postmortem.md --force
horus postmortem <id> --ai-summary

Options: -c, --config <path>, --output <path>, --force, --ai-summary, --ai-model <model>, --refresh-ai

Self-routing and Suggested next

Several commands end with a deterministic Suggested next block: an ordered list of advisory commands that fit the result you just got. The router is pure and deterministic — it suggests, it never runs anything — and every suggestion is a real shipped command (init, search, blast-radius, explain, connect <type>, readiness, investigate, and so on). It never fabricates a connector or flag that does not exist.

The same suggestions are available as structured data: pass --json to any supporting command for a nextSteps array, and Horus MCP tools return the equivalent suggestedNextTools so a coding agent can chain the next call itself.

Source-intelligence commands

horus explain <query>

Explain a symbol: location, community, callers/callees, impact, and related flows.

horus explain AuthService.login
horus explain AuthService.login --depth 2 --json

Options: -c, --config <path>, -d, --depth <n>, --repo <name>, --json, --full (uncapped JSON: full neighbour lists, per-depth impact, and snippets; also includes test callers)

horus search <query>

Search symbols across all configured repositories.

horus search "checkout"
horus search "checkout" --limit 10 --json

Options: -c, --config <path>, -n, --limit <n>, --json

horus repos

List configured repositories and their source-intelligence host health.

horus repos

Options: -c, --config <path>

horus queues [name]

Show queue topology from source intelligence. Add --live to fetch real-time Redis/BullMQ state.

horus queues
horus queues checkout-jobs --live

Options: -c, --config <path>, --live, --json, --ai, --ai-model <model>

Change-impact commands

horus changes <base> [compare]

Show what changed between two git refs and which flows are affected.

horus changes HEAD~5
horus changes v1.0.0 HEAD --json

Options: -c, --config <path>, --json, --full (uncapped raw JSON; compact by default), --ai, --ai-model <model>

horus timeline [service]

Reconstruct what changed in a time window from git and change-impact evidence.

horus timeline --since "7 days ago" --json
horus timeline atlas-payments --since 2026-06-01 --until 2026-06-15

Options: -c, --config <path>, --repo <name>, --since <when>, --until <when>, --all, --json, --full (uncapped raw JSON; compact by default), --ai, --ai-model <model>

horus what-changed [service]

Concise, evidence-backed summary of what changed for a service in a time window.

horus what-changed atlas-payments --since "7 days ago"

Options: -c, --config <path>, --repo <name>, --since <when>, --until <when>, --json, --full (uncapped raw JSON; compact by default), --push

horus architecture

Discover the living architecture: subsystems, async boundaries, external systems, and fragility.

horus architecture
horus architecture --json

Options: -c, --config <path>, --json, --ai, --ai-model <model>

horus blast-radius <query>

Failure-propagation analysis: upstream/downstream dependencies plus blast radius across async boundaries.

horus blast-radius PaymentGateway
horus blast-radius PaymentGateway --depth 2 --json

Options: -c, --config <path>, -d, --depth <n>, --include-tests (include test/example callers — product-only by default), --json, --ai, --ai-model <model>

Runtime evidence commands

horus logs [service]

Synthesize error evidence from logs: signatures, first/last occurrences, and affected services. Use --raw for individual log lines.

horus logs atlas-payments --since 24h
horus logs atlas-payments --raw --limit 100 --level error

Options: -c, --config <path>, --env <name>, --since <when>, --level <level>, --grep <text>, --where <field=value> (filter by a structured context field; repeatable, AND-combined; e.g. --where context.brand_id=42), --raw, --all-levels, --group-by <field>, --limit <n>, --json, --ai, --ai-model <model>

horus metrics [hint]

Grafana metrics evidence: find dashboards/panels for a hint and detect latency spikes, error-rate changes, throughput drops, and queue growth.

horus metrics "checkout latency" --since 1h
horus metrics --dashboard abc123 --json

Options: -c, --config <path>, --since <when>, --step <secs>, --dashboard <uid>, --query <promql>, --json, --ai, --ai-model <model>

horus state

Surface application-state evidence from MongoDB (read-only, allowlisted): counts, staleness, and anomalous statuses.

horus state --env production
horus state --stale-hours 12

Options: -c, --config <path>, --env <name>, --stale-hours <n>, --json, --ai, --ai-model <model>

Memory commands

horus memory manages project-scoped incident memory: durable claims and confirmed outcomes that Horus can recall as context on later runs. Memory is offline and project-isolated — an unresolved project is an error, never a silent unscoped run. It is context only and never feeds the confidence/verdict scoring path. See the Memory page for the full model.

horus memory show <scope>

Synthesize owned areas, runtime paths, past investigations, and weak spots for a scope, then list the stored memory items recalled for it.

horus memory show CheckoutController
horus memory show packages/payments --json

Options: -c, --config <path>, --repo <name>, --json

horus memory add <claim>

Add an authored memory claim (a human-sourced fact, decision, contract, or pitfall) for the repo.

horus memory add "Checkout retries are not idempotent" --kind pitfall --evidence pr:1421

Options: -c, --config <path>, --repo <name>, --scope <scope> (global|repo|module:<area>|symbol:<node_id>), --kind <kind> (code-fact|contract|decision|pitfall|incident-pattern), --evidence <kind:ref> (repeatable), --confidence <0..1>, --json

horus memory confirm <investigationId>

Record a confirmed-outcome memory item from an investigation. The item is stored private and PII-gated, linked back to the investigation, and writes a durable yes outcome label into the accuracy eval set.

horus memory confirm <id> --note "root cause was the missing index"

Options: -c, --config <path>, --repo <name>, --note <note>, --json

horus memory list

List persisted authored memory items for the repo. Add --all to include forgotten, deprecated, and contradicted items.

horus memory list
horus memory list --all --json

Options: -c, --config <path>, --repo <name>, --all, --json

horus memory forget <id> / horus memory pin <id>

forget soft-deletes an item — it is retained and audited, excluded from recall, and reversible. pin floats an item to the top of recall so it is never auto-hidden by staleness.

horus memory forget <id> --note "superseded"
horus memory pin <id>

Options: -c, --config <path>, --note <note>, --json

horus memory link / unlink / detect

horus memory link <a> <b> --rel <rel> authors a typed edge between two memory items, where --rel is one of supersedes, contradicts, or recurs-with (supersedes and contradicts are directional; recurs-with is symmetric). horus memory unlink <a> <b> --rel <rel> removes the edge. horus memory detect conservatively auto-proposes recurrence and contradiction edges; --dry-run previews them without writing.

horus memory link <a> <b> --rel supersedes
horus memory link <a> <b> --rel recurs-with
horus memory detect --dry-run

Options: --rel <rel> (required for link/unlink), -c, --config <path>, --repo <name>, --note <note>, --json; detect also takes --dry-run and --limit <n>.

horus memory accuracy

Report Horus's measured hit-rate from the converged outcome-label eval set — how often Horus pointed at the cause, across confirmed investigations and feedback verdicts.

horus memory accuracy
horus memory accuracy --days 30 --source feedback --json

Options: -c, --config <path>, --repo <name>, --source <feedback|confirm>, --days <n>, --since <date> (only count labels on/after this date), --all (count full retained history, disabling the default recent window), --limit <n>, --json

horus memory sync

Push local memory items (and their links and audit trail) to the linked cloud project. Idempotent and best-effort. Recall vectors are local-only and are never synced.

horus memory sync --dry-run
horus memory sync --yes

Options: -c, --config <path>, --repo <name>, --limit <n>, --dry-run, --yes, --json

Utility and feedback commands

horus feedback [investigationId]

Leave quick impact feedback on an investigation: did Horus point at the cause? A non-interactive mode is available for agents and scripts: pass --resolved <verdict> where the verdict is yes, partly, or no, and optionally --manual-estimate-min <minutes>. Without flags in a terminal, Horus prompts interactively.

Each concrete verdict persists a durable outcome label into the local eval set — the same store horus memory confirm writes to — so horus memory accuracy can report Horus's measured hit-rate over time. Persistence is best-effort and never blocks the feedback itself.

horus feedback <id> --resolved yes --manual-estimate-min 30

Options: --resolved <verdict>, --manual-estimate-min <minutes>, --cause <text> (human-confirmed root cause recorded onto the outcome label; pair with --resolved), --note <text> (free-text context; pair with --resolved), -c, --config <path>, --repo <name>

horus report [hint]

File a Horus bug or capability gap as a pre-filled GitHub issue on meritt-dev/horus. Horus opens your browser at a new-issue form already populated with a title, an environment block (CLI + source-intelligence version, OS, Node), and any hint you pass — nothing is submitted automatically and no authentication is required. Reach for it when Horus crashes, returns the wrong cause, or is missing a capability you need.

This is distinct from horus feedback: feedback teaches Horus whether an investigation was right (the accuracy corpus); report files a bug or gap for the Horus team to fix.

horus report "explain crashes on monorepos"
horus report --title "Axiom connector ignores --service" --labels bug,connectors

Options: --title <text>, --body <text>, --labels <list>, -c, --config <path>

Agents driving Horus over MCP can file the same pre-filled issue through the report_issue tool when they detect a Horus limitation mid-task — the highest-leverage path, since agents see Horus's failure modes firsthand.

horus telemetry

Manage anonymous usage telemetry. Subcommands: status, enable, disable, enable-content, disable-content, reset-id, and delete. By default, usage metadata is ON and content sharing is OFF. Hard opt-out via the environment with HORUS_TELEMETRY=0 or DO_NOT_TRACK=1.

horus telemetry status
horus telemetry disable
horus telemetry enable-content

horus owner <query>

Estimate who likely owns a component from git history, with confidence and evidence.

horus owner PaymentGateway --json

Options: -c, --config <path>, --repo <name>, --json

horus score <id>

Score a saved investigation's quality. This is a feedback loop for Horus, not for engineers.

horus score <id> --json

Options: -c, --config <path>, --json, --ai, --ai-model <model>

horus ask <id> <directive>

Ask about or refine a saved investigation — reuses evidence, except code-locating questions re-query the source host for fresh file:line citations. As well as topic filters (focus on queue behavior, ignore deployment changes, retry), it answers direct questions like what evidence contradicts <topic>?, what evidence is missing?, why is confidence not higher?, and code-locating questions like where is processOrder defined? or which file has OrderService?.

horus ask <id> "focus on queue behavior"
horus ask <id> "ignore deployment changes" --json

Options: -c, --config <path>, --json

horus scores

List recent investigation quality scores and the average trend.

horus scores -n 20
horus scores --json

Options: -c, --config <path>, -n, --limit <n>, --json

eval

Read-only accuracy harness over Horus's outcome-label eval set (never writes labels).

• horus eval build — emit a byte-stable corpus. Options: --source <feedback|confirm>, --days <n>, --limit <n>, --out <dir> (default ./.horus/eval), --version <v> (default v1), --repo, -c, --config, --json.
• horus eval baseline — print baseline hit-rate and a feature-separation diagnostic. Options: --source <feedback|confirm>, --days <n>, --limit <n>, --repo, -c, --config, --json.

Knowledge index commands

horus knowledge queries the local project-knowledge index (.horus/index) — offline, no Cloud required. It answers questions about your codebase's operations, types, concepts, and data flow, grounded in the index.

horus knowledge status

Show the last indexed commit, schema version, item counts, and stale/dirty status. Add --cloud to compare the local index with the linked cloud snapshot.

horus knowledge search <query>

Keyword search across indexed operations, types, concepts, and patterns.

horus knowledge contracts <name>

Show operations, types, enums, and auth rules verbatim — no hallucinated values.

horus knowledge trace <query>

Walk known concept ↔ operation ↔ type and data-flow links.

horus knowledge ask <question>

Get a grounded answer from the local index, with provenance — fully offline.

horus knowledge validate / push / pull

validate checks the index (schema, content hash, staleness) and is pre-push friendly. push uploads the local snapshot to the linked cloud project (--dry-run to preview; content-hash deduped). pull downloads the latest cloud snapshot (--force to overwrite differing local knowledge).

Cloud and account commands

horus login

Log in to Horus Cloud. Stores a CLI token in ~/.horus/auth.json (never in the repo). Use --token <token> or set HORUS_TOKEN; --api-url (or HORUS_CLOUD_API_URL) overrides the API base URL.

horus logout

Revoke the current CLI token and clear local credentials.

horus context

Select where this repo stores investigations — local or a cloud project.

• horus context list — list the local context and the cloud contexts you can use.
• horus context use <target> — switch to local or <org>/<workspace>/<project>.
• horus context show — show the active context and the selected project's sync metadata.

horus cloud

Link this repo to a Horus Cloud project and inspect cloud state.

• horus cloud link [target] — link the current repo to a cloud project; pass the target positionally (horus cloud link <org/workspace/project>) to skip the interactive picker. -y, --yes to skip confirmation prompts.
• horus cloud unlink — remove the cloud link and return to local mode.
• horus cloud status — show context, linked project, sync metadata, and auth state.
• horus cloud sync — upload existing local investigations to the linked project (--dry-run, --limit <n>, --yes).

Other commands

The CLI also ships helper commands that are not part of the core investigation workflow:

• horus projects — list projects registered in ~/.horus/registry.json.
• horus providers doctor — check which local AI providers are available.
• horus watch — proactively monitor Sentry/Elasticsearch and auto-investigate each new incident (--source, --interval, --once).
• horus mcp — run the Horus MCP server (stdio), exposing the local knowledge index to agents.
• horus skill install <target> — install the Horus agent skill (claude | codex | gemini | cursor | generic); also skill print and skill path. --force and --global (install into your home dir instead of the repo) are supported on skill install; --global is also accepted on skill path.
• horus update — update Horus to the latest GitHub release (--check, --force).
• horus onboard [area] — understand a system fast; experimental.
• horus simulate [scenario] — practice an incident with a synthetic scenario; experimental.

notify

Configure the outbound notify sink for horus watch — confident auto-investigations are dispatched to a webhook and, optionally, pushed to Horus Cloud.

• horus notify set — --url <url>, --secret <secret> (HMAC signing key, stored encrypted), --min-confidence <n> (0..1, default 0.6), --cloud / --no-cloud, --env <name>, -c, --config <path>.
• horus notify show — print the current sink (secret masked). Options: --env, -c, --config.
• horus notify test — send a sample signed dispatch. Options: --env, -c, --config.
• horus notify remove — delete the sink. Options: --env, -c, --config.

secrets

Manage encrypted connector credentials in .horus/secrets.local.json (HOR-452).

• horus secrets status — show the master-key source, stored secrets, any plaintext still in config, and gitignore state.
• horus secrets migrate — move plaintext connector secrets out of config.json into the encrypted store. --dry-run to preview.
• horus secrets key — --show prints the base64 master key for CI (set it as HORUS_SECRET_KEY).

train

Fit the local, per-tenant reranker over your outcome-label corpus (off until it beats baseline). Options: -c, --config <path>, --source <feedback|confirm>, --days <n>, --limit <n>.