cli-reference.md

CLI reference

Maintainer and automation commands for codestory-cli. You should not need this page for first install — start with user guides, then Trust and readiness and Troubleshooting if a session is blocked.

Plain-language readiness lanes: Trust and readiness. Runtime status field glossary (agents): status-contract.

Install: download the release binary from GitHub release assets for your platform. Building from source is a contributor setup path:

export CODESTORY_EMBED_MODEL_SOURCE="$(node scripts/prepare-embedded-model.mjs)"
cargo build --release --locked -p codestory-cli

In PowerShell, prepare with $env:CODESTORY_EMBED_MODEL_SOURCE = node scripts/prepare-embedded-model.mjs. Windows binary: .\target\release\codestory-cli.exe.

Generated codestory-cli --help and subcommand help are the source of truth for flags. This page groups stable workflows and trust boundaries rather than copying every option.

Readiness and retrieval

Situation	Command
Agent handoff when MCP is down	codestory-cli agent preflight --project <repo> --format json
Refresh local graph	codestory-cli index --project <repo> --refresh auto --format json
Build packet/search retrieval	codestory-cli retrieval index --project <repo> --refresh full --format json
Health summary	codestory-cli doctor --project <repo>
Managed search status	codestory-cli retrieval status --project <repo> --format json
Direct single-project stdio MCP (debug)	codestory-cli serve --project <repo> --stdio --refresh none

Preflight exposes safe_surfaces, blocked_surfaces, and the next normal retrieval action. ready --format json returns verdicts[] with per-goal status, summary, and minimum_next. retrieval status --format json reports retrieval_mode (trust packet/search only when full). When MCP is live, prefer the project-bound codestory://status{?project} resource instead.

Local navigation

codestory-cli ground --project <repo> --why
codestory-cli files --project <repo> --path src --limit 80
codestory-cli symbol --project <repo> --id <node-id>
codestory-cli trail --project <repo> --id <node-id> --story --hide-speculative
codestory-cli snippet --project <repo> --id <node-id> --context 40
codestory-cli affected --project <repo> --format markdown

Pipe changed files for impact hints:

git diff --name-only HEAD | codestory-cli affected --project <repo> --stdin --format json

Impact hints are not test results.

Packet and search

Only trust output when retrieval status reports retrieval_mode: "full".

codestory-cli packet --project <repo> --question "<broad task question>"
codestory-cli search --project <repo> --query "<symbol or behavior>" --why

Packets use the standard evidence budget by default. Pass --budget compact when minimizing context matters more than keeping the fuller evidence set.

Degraded retrieval is navigation help only. See Glossary.

Stale local cache

codestory-cli index --project <repo> --refresh auto --format json

Read commands default to --refresh none. Use --refresh incremental when a read should refresh a compatible existing cache first. Explicit incremental refresh never escalates to full: incompatible structural publication returns the typed full_refresh_required error before workspace discovery or parsing, as does a supported pre-current schema. Use --refresh auto when CodeStory may choose full recovery for an empty or incompatible cache. Index dry-run output reports the requested mode, effective mode, and compatibility reason.

Reserve index --refresh full or moving a cache aside for maintainer-directed recovery after status or doctor identifies that exact cache and coordinated refresh cannot converge. Verify the path is under the active CodeStory cache root, preserve the old directory until the replacement is healthy, and never clean a user cache merely to make tests pass.

Roll a retrieval generation back

CodeStory retains one deeply verified previous retrieval generation beside the current one. When broad retrieval stops being live-ready but the retained generation still proves out, activate it instead of rebuilding:

codestory-cli retrieval activate-rollback --project <repo> --dry-run
codestory-cli retrieval activate-rollback --project <repo>

--dry-run runs every validation and changes nothing. Activation re-proves the retained generation against the live core publication and the artifacts on disk before it moves the pointer, so it can only ever refuse — with a typed code such as rollback_evidence_invalid or rollback_not_live_ready — never serve something the normal publication fence would have rejected. Activation consumes the retained pointer: the generation you stepped away from is not re-armed as a rollback target.

doctor reports the retained generation and recommends this command when retrieval is not live-ready. doctor never activates anything itself.

Downgrade to an older CodeStory

Schema migrations are forward-only. An older CodeStory pointed at a cache a newer release wrote fails closed with Unsupported database schema version, and --refresh full fails closed on it too. That is deliberate: the alternative is destroying a newer database. The executable recovery is to quarantine the derived cache and rebuild it.

codestory-cli cache reset --project <repo> --derived-only --dry-run
codestory-cli cache reset --project <repo> --derived-only --confirm
codestory-cli index --project <repo> --refresh full
codestory-cli retrieval index --project <repo> --refresh full
codestory-cli doctor --project <repo> --format markdown

cache reset requires --derived-only and exactly one of --dry-run or --confirm. It moves derived state — the core database and its SQLite siblings, the rollback backup, promotion journals, the search trees, and local-refresh state — into a timestamped derived-reset-quarantine/ directory inside the same cache root. Nothing is deleted, so a mistaken reset is recoverable by moving the quarantined files back. It never opens the database, which is what makes it usable against a schema it cannot read.

User-authored annotations live in a sidecar beside the cache and are preserved in place; the command reports exactly what it moved and what it preserved. The reset holds this project's index-writer and promotion locks for the whole move, so a concurrent indexing run or publication either finishes first or is refused with cache_busy; if neither releases within the wait budget the reset itself refuses and moves nothing.

Retrieval generations are reclaimed separately by codestory-cli retrieval inventory --project <repo> --apply once the rebuild has published a new generation.

Index and ground

codestory-cli index --project <repo> --refresh auto
codestory-cli ground --project <repo> --why

Output and configuration

Most commands default to Markdown. Use --format json for automation.

Optional project members file:

{
  "members": ["backend/", "frontend/", "shared/"]
}

Team or user defaults: .codestory.toml at project root or user home. Home file loads first; project file overrides for project-safe preferences. Environment variables win over files.

Configuration is resolved independently for each project and retained for the life of that project runtime. Multi-project stdio captures the user home, project-network opt-in, cache root, and runtime environment once; it neither rewrites nor re-reads them when requests switch repositories.

Configuration reference lists every honoured .codestory.toml key and environment variable; it is generated from the one registry the code reads, so a key that is absent there does nothing. Embedding query and document prefixes are compile-time constants of the pinned model and are not configurable. A file may declare schema_version: version 1 (the default when the key is absent) warns about unknown keys by name and ignores them, version 2 rejects them, and a higher version fails with unsupported_config_schema.

Project .codestory.toml cannot choose cache roots. It also cannot choose network egress settings by default. A trusted operator may set CODESTORY_ALLOW_PROJECT_NETWORK_CONFIG=1 for the whole process to allow every project opened by that process to configure summary endpoints. That opt-in can redirect source text, so never enable it while opening untrusted repositories. Embedding never uses a network endpoint. Put cache_dir in user home .codestory.toml or pass --cache-dir.

Command by situation

Stuck situation	First command	Use next
Orientation	ground --project <repo> --why	files for language mix or coverage gaps
Where to edit	symbol --project <repo> --query "<feature>"	callers, callees, trail after picking a node
Change impact	affected with --stdin from git diff	Pick focused tests; not a test run
Readiness	agent preflight --format json	codestory://status{?project} when MCP is live
Broad evidence	retrieval status --format json	packet or search only after full mode
Broad retrieval broke and a rollback is retained	retrieval activate-rollback --project <repo> --dry-run	Rerun without --dry-run once validation passes
Rolled back CodeStory onto a newer cache	cache reset --project <repo> --derived-only --dry-run	--confirm, then index --refresh full

Managed search internals

Maintainer-only engine details: retrieval operations.

Environment overrides

Variable	Purpose
CODESTORY_CLI	Local-dev override for MCP adapter binary path
CODESTORY_IDE_COMMAND	Optional shell command template for definition-open actions. Supports {file}, {line}, and {col}; set only trusted local templates because the template runs through your shell.
CODESTORY_NO_TUI	Disable TUI for explore in CI or scripts
CODESTORY_SUMMARY_ENDPOINT	Trusted summary endpoint
CODESTORY_ALLOW_PROJECT_NETWORK_CONFIG	Process-wide opt-in allowing trusted project files to configure summary endpoints

CPU embeddings are unsupported. Broad retrieval requires an eligible Metal or Vulkan device and never falls back to CPU.

Further reading

• Troubleshooting
• Contributor debugging
• Glossary