Kasava CLI

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

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.

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.

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:

Detect the repo — reads git remote get-url origin and parses owner/name.
Match against your products — checks linked repositories on each product, matches by fullName, htmlUrl, or cloneUrl.
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.
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)

File	Commit?	Refreshed by
`config.json`	no	`kasava install`
`PRODUCT_MAP.md`	yes	`kasava sync`
`graph.json`	yes	`kasava sync`
`work-items.json`	yes	`kasava sync`
`symbols.json`	no	`kasava sync`
`plans/*.md`	yes	`kasava 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

Command	Flags
`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

Variable	Effect
`KASAVA_TOKEN`	API key — takes precedence over `~/.kasava/credentials`
`KASAVA_API_KEY`	Alias for `KASAVA_TOKEN`
`KASAVA_API_URL`	Override the API base (default `https://api.kasava.dev`)

File locations

Path	What lives there
`~/.kasava/credentials`	Saved 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

"Could not detect a git origin remote"

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.

"Searched N products but none have <repo> linked"

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.

Multiple products match my repo

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.

"Could not verify token: 401"

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.

"No credits remaining" on `--ai`

kasava sync --ai and kasava ask --ai both consume credits. Visit Settings → Billing to top up, or drop --ai for free deterministic / offline behavior.

I want to disable the Claude Code plugin

kasava uninstall only manages the local .kasava/ artifact. To disable the plugin, run /plugin disable kasava inside Claude Code.

Getting Started

Concepts

Core Features

Agent Capabilities

Integrations

Developer Tools

Settings

Commands

Install

Authenticate

Bind a repo

What `.kasava/` looks like after `kasava sync`

Sync

Read a plan

Ask the artifact

Per-file context

Staleness + decisions

Reference

Commands

Environment variables

File locations

Troubleshooting

​Commands

​Install

​Authenticate

​Bind a repo

​What .kasava/ looks like after kasava sync

​Sync

​Read a plan

​Ask the artifact

​Per-file context

​Staleness + decisions

​Reference

​Commands

​Environment variables

​File locations

​Troubleshooting

Commands

Install

Authenticate

Bind a repo

What `.kasava/` looks like after `kasava sync`

Sync

Read a plan

Ask the artifact

Per-file context

Staleness + decisions

Reference

Commands

Environment variables

File locations

Troubleshooting