Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kasava.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Kasava CLI is the headless / scriptable / terminal-first surface for Kasava. It binds a local repository to a Kasava product and writes a .kasava/ directory with synthesized product context, plans, work breakdowns, graph, and a top-symbols index. The Claude Code plugin reads from that artifact when present — no token cost — and falls through to MCP for live data.
Three surfaces, one product. The Kasava web app is where you create plans and view dashboards. The Claude Code plugin gives you those plans + intelligence inside your IDE. The CLI is the terminal-first companion — useful for CI cron, post-merge git hooks, scripts, and headless workflows.

​
Commands

login              Save a Kasava API key locally
logout             Delete saved credentials
whoami             Show which token + API URL are in use
install            Bind this repo to a Kasava product (writes .kasava/)
uninstall          Remove the local .kasava/ artifact (with --remove-artifact)
sync               Pull plans, work items, graph, and symbols into .kasava/
plan               Print the agent-spec for a synced plan
ask                Search the local .kasava/ artifact for a question (offline)
staleness          List stale documents for the bound product
decisions add      Record a decision on the bound product
ownership          Show top contributors for a file (commit history + CODEOWNERS)
rationale          Show inline TODO/FIXME plus plan/spec/decision docs that reference a file
env                Print export lines for KASAVA_TOKEN (eval to source into your shell)
The --ai flags on sync and ask are opt-in and consume Kasava credits.

​
Install

npm i -g @kasava/cli
# or: pnpm add -g @kasava/cli
From source: 
git clone https://github.com/kasava-dev/kasava
cd kasava/external/kasava-cli
pnpm install
pnpm build
pnpm link --global

​
Authenticate

1

Create an API key

Go to Settings → API Keys in the Kasava web app and click Create API Key. The key is shown once — copy it before closing the dialog.
2

Save the token

kasava login
# paste the kasava_live_… or kasava_test_… token at the prompt
The CLI verifies the token against GET /api/products, then writes it to ~/.kasava/credentials at mode 0600.For CI / non-interactive use: export the token as an environment variable.
export KASAVA_TOKEN=kasava_live_…
kasava whoami
The CLI prefers KASAVA_TOKEN over the saved file when both are present.
3

Optional: source the token into your shell

Once you’ve run kasava login, you can export KASAVA_TOKEN to all subprocesses with:
eval "$(kasava env)"             # bash / zsh
kasava env --shell fish | source # fish
kasava env >> ~/.zshrc           # persist
The same key works in the Claude Code plugin — paste it once into the plugin’s userConfig field.

​
Bind a repo

Run inside any git repository whose origin remote is linked to a Kasava product. 
cd /path/to/your/repo
kasava install
What happens:
  1. Detect the repo — reads git remote get-url origin and parses owner/name.
  2. Match against your products — checks linked repositories on each product, matches by fullName, htmlUrl, or cloneUrl.
  3. Disambiguate — if multiple products link the repo (e.g., a monorepo backing several), the CLI prompts you to pick. Pass --product-id <id> to skip detection.
  4. Write the artifact — creates .kasava/config.json, .kasava/PRODUCT_MAP.md placeholder, and .kasava/plans/.
The CLI does not install anything in ~/.claude/. The Claude Code plugin owns Claude Code state; install it separately with /plugin install kasava@kasava-dev.

​
What .kasava/ looks like after kasava sync

.kasava/
├── config.json              ← repo→product binding (gitignored, no secrets)
├── PRODUCT_MAP.md           ← synthesized product overview (committed)
├── graph.json               ← product graph snapshot (committed)
├── work-items.json          ← per-plan work breakdowns + linked items (committed)
├── symbols.json             ← top exported symbols (gitignored cache)
├── staleness.md             ← (placeholder, populated when API exposes it)
└── plans/
    └── <slug>.md            ← agent-spec markdown per active plan (committed)
FileCommit?Refreshed by
config.jsonnokasava install
PRODUCT_MAP.mdyeskasava sync
graph.jsonyeskasava sync
work-items.jsonyeskasava sync
symbols.jsonnokasava sync
plans/*.mdyeskasava sync
The default .kasava/.gitignore keeps secrets and large caches local while letting the synthesized overview, plans, graph, and work breakdowns ride along with your code so teammates inherit the context.

​
Sync

kasava sync                 # pull plans + work items + graph + top 200 symbols
kasava sync --no-symbols    # skip symbol fetch
kasava sync --symbols-limit 500
kasava sync --ai            # also append AI-synthesized PRODUCT_MAP sections (BILLABLE)
Without --ai, sync is deterministic and free. With --ai, the backend appends three synthesized sections to PRODUCT_MAP.md — god items, surprising links, suggested questions — via a single Haiku call.

​
Read a plan

kasava plan onboarding              # exact slug match
kasava plan "Improve onboarding"    # exact title match
kasava plan onboard                 # partial match
kasava plan abc123 --no-pager       # by ID, raw stdout
Resolves by exact slug, exact title, then partial match across .kasava/plans/. Each plan markdown carries an “View in Kasava → app.kasava.dev/products/…/initiatives/…” header so you can pivot to the web app at any time.

​
Ask the artifact

kasava ask "what touches billing?"          # offline keyword search (free)
kasava ask "what's blocking auth?" --ai     # stream a live agent answer (BILLABLE)
Default mode is offline keyword search across .kasava/PRODUCT_MAP.md, plans/*.md, symbols.json, and graph.json. With --ai, the CLI streams an answer from a focused Haiku agent that has product graph + symbol + doc-search tools.

​
Per-file context

kasava ownership src/auth/login.ts          # top contributors (last 90 days, max 5)
kasava ownership "src/auth/*" --days 180    # glob + custom lookback
kasava ownership src/auth/login.ts --json   # scriptable

kasava rationale src/auth/login.ts          # inline TODO/FIXME + plan/decision refs
kasava rationale src/auth/login.ts --branch develop
kasava rationale src/auth/login.ts --json
ownership queries /repositories/:id/ownership/file (commit history; CODEOWNERS-aware once that data is indexed). rationale queries /repositories/:id/rationale and returns inline annotated comments (TODO / FIXME / HACK / NOTE) plus any published plans, specs, or decision docs that reference the file via document_code_references.

​
Staleness + decisions

kasava staleness            # list stale documents under the bound product
kasava staleness --json     # raw JSON output, scriptable
kasava staleness --limit 50

kasava decisions add "Use Drizzle for ORM" --type technology --rationale "..."
kasava decisions add "Adopt Tanstack Query" --edit-rationale   # opens $EDITOR
Decision types: architecture, technology, feature, process, scope. Default is feature. Each successful add returns a deep link to app.kasava.dev/products/<id>/decisions/<id>.

​
Reference

​
Commands

CommandFlags
kasava login--token … --api-url … --no-verify
kasava logout—
kasava whoami—
kasava install--product-id … -y --verbose
kasava uninstall--remove-artifact -y
kasava sync--no-symbols --symbols-limit N --ai --verbose
kasava plan <name|slug|id>--no-pager
kasava ask "<q>"--ai --limit N
kasava staleness--limit N --json
kasava decisions add "<summary>"--type <T> --rationale <R> --edit-rationale
kasava ownership <file>--days N --limit N --json
kasava rationale <file>--branch <name> --max-comments N --max-documents N --json
kasava env--shell bash|fish

​
Environment variables

VariableEffect
KASAVA_TOKENAPI key — takes precedence over ~/.kasava/credentials
KASAVA_API_KEYAlias for KASAVA_TOKEN
KASAVA_API_URLOverride the API base (default https://api.kasava.dev)

​
File locations

PathWhat lives there
~/.kasava/credentialsSaved token (mode 0600)
<repo>/.kasava/Per-repo product binding + cached context
The CLI does not write anywhere else under ~/.claude/. That’s the Claude Code plugin’s job.

​
Troubleshooting

Run kasava install from inside a git repository that has an origin remote pointing at GitHub. If you only have a local repo, add a remote first or pass --product-id <id> to skip detection.
Add the repository to a Kasava product first (Products → your product → Repositories), then re-run kasava install. The CLI matches on fullName, htmlUrl, and cloneUrl, so any of those will work.
A monorepo can back several Kasava products. The CLI prompts you to pick interactively; pass --product-id <id> to bind without prompting, or -y to refuse to guess and exit.
The token format looked right but the API rejected it. Generate a fresh key at Settings → API Keys. If your organization uses a non-default API URL, pass --api-url to kasava login or set KASAVA_API_URL.
kasava sync --ai and kasava ask --ai both consume credits. Visit Settings → Billing to top up, or drop --ai for free deterministic / offline behavior.
kasava uninstall only manages the local .kasava/ artifact. To disable the plugin, run /plugin disable kasava inside Claude Code.