> ## 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.

# Kasava CLI

> Bind a repository to a Kasava product, sync product context into a checked-in `.kasava/` artifact, and run terminal-first queries against your product

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](/docs/developer/claude-code-plugin) reads from that artifact when present — no token cost — and falls through to MCP for live data.

<Note>
  **Three surfaces, one product.** The [Kasava web app](https://app.kasava.dev) is where you create plans and view dashboards. The [Claude Code plugin](/docs/developer/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.
</Note>

## Commands

```text theme={null}
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

```bash theme={null}
npm i -g @kasava/cli
# or: pnpm add -g @kasava/cli
```

From source:

```bash theme={null}
git clone https://github.com/kasava-dev/kasava
cd kasava/external/kasava-cli
pnpm install
pnpm build
pnpm link --global
```

## Authenticate

<Steps>
  <Step title="Create an API key">
    Go to [**Settings → API Keys**](https://app.kasava.dev/settings/api-keys) in the Kasava web app and click **Create API Key**. The key is shown once — copy it before closing the dialog.
  </Step>

  <Step title="Save the token">
    ```bash theme={null}
    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.

    ```bash theme={null}
    export KASAVA_TOKEN=kasava_live_…
    kasava whoami
    ```

    The CLI prefers `KASAVA_TOKEN` over the saved file when both are present.
  </Step>

  <Step title="Optional: source the token into your shell">
    Once you've run `kasava login`, you can export `KASAVA_TOKEN` to all subprocesses with:

    ```bash theme={null}
    eval "$(kasava env)"             # bash / zsh
    kasava env --shell fish | source # fish
    kasava env >> ~/.zshrc           # persist
    ```

    The same key works in the [Claude Code plugin](/docs/developer/claude-code-plugin) — paste it once into the plugin's userConfig field.
  </Step>
</Steps>

## Bind a repo

Run inside any git repository whose `origin` remote is linked to a Kasava product.

```bash theme={null}
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)
```

| 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/docs/developer/claude-code-plugin)'s job.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Could not detect a git origin remote&#x22;">
    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.
  </Accordion>

  <Accordion title="&#x22;Searched N products but none have <repo> linked&#x22;">
    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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="&#x22;Could not verify token: 401&#x22;">
    The token format looked right but the API rejected it. Generate a fresh key at [Settings → API Keys](https://app.kasava.dev/settings/api-keys). If your organization uses a non-default API URL, pass `--api-url` to `kasava login` or set `KASAVA_API_URL`.
  </Accordion>

  <Accordion title="&#x22;No credits remaining&#x22; on `--ai`">
    `kasava sync --ai` and `kasava ask --ai` both consume credits. Visit [Settings → Billing](https://app.kasava.dev/settings/billing) to top up, or drop `--ai` for free deterministic / offline behavior.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>