Skip to content

cli-reference.md

Latest commit

 

History

History
148 lines (110 loc) · 5.92 KB

cli-reference.md

File metadata and controls

148 lines (110 loc) · 5.92 KB
Raw

CLI reference

Power-user and debug 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:

cargo build --release --locked -p codestory-cli

Windows: .\target\release\codestory-cli.exe.

Readiness and repair

Situation Command
Agent handoff when MCP is down codestory-cli agent preflight --project <repo> --format json
Repair local graph codestory-cli ready --goal local --repair --project <repo> --format json
Repair packet/search codestory-cli ready --goal agent --repair --project <repo> --format json
Health summary codestory-cli doctor --project <repo>
Sidecar status codestory-cli retrieval status --project <repo> --format json
Direct stdio MCP (debug) codestory-cli serve --project <repo> --stdio --refresh none

Preflight exposes safe_surfaces, blocked_surfaces, and repair_command. ready --format json returns verdicts[] with per-goal status, summary, minimum_next, and full_repair. retrieval status --format json reports retrieval_mode (trust packet/search only when full). When MCP is live, prefer codestory://status 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>" --budget compact
codestory-cli search --project <repo> --query "<symbol or behavior>" --why

Degraded retrieval is navigation help only. See Glossary.

Stale local cache

codestory-cli ready --goal local --repair --project <repo> --format json

Read commands default to --refresh none. Use --refresh incremental when a read should refresh an existing cache first.

Reserve index --refresh full or moving a cache aside for maintainer-directed recovery after status/doctor identifies that exact cache and coordinated local repair 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.

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. 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 and embedding endpoints. That opt-in can redirect source or query text, so never enable it while opening untrusted repositories. 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 when MCP is live
Broad evidence retrieval status --format json packet or search only after full mode

Sidecar setup

Product sidecar setup: Retrieval sidecars ops.

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_EMBED_LLAMACPP_URL Trusted embedding endpoint
CODESTORY_ALLOW_PROJECT_NETWORK_CONFIG Process-wide opt-in allowing trusted project files to configure network endpoints

Further reading