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: release binary from GitHub assets, or build from source:
export CODESTORY_EMBED_MODEL_SOURCE="$(node scripts/prepare-embedded-model.mjs)"
cargo build --release --locked -p codestory-cliIn 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.
| 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.
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 markdownPipe changed files for impact hints:
git diff --name-only HEAD | codestory-cli affected --project <repo> --stdin --format jsonImpact hints are not test results.
Only trust output when retrieval status reports retrieval_mode: "full".
codestory-cli packet --project <repo> --question "<broad task question>" --budget compact
codestory-cli search --project <repo> --query "<symbol or behavior>" --whyDegraded retrieval is navigation help only. See Glossary.
codestory-cli index --project <repo> --refresh auto --format jsonRead 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.
codestory-cli index --project <repo> --refresh auto
codestory-cli ground --project <repo> --whyMost 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. Trusted project files
may also set embedding_query_prefix and embedding_document_prefix as part of
their per-project embedding contract.
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.
| 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 |
Maintainer-only engine details: retrieval operations.
| 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.