> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# CLI

The `khotan` CLI is the first-party command-line interface for the Khotan API.
It is a thin adapter over `/api/v1`, driven by a shared capability catalog.
Adding a command updates `khotan help` and these pages together.

## Start here

```sh
npx @khotan/cli --help
```

Then authenticate once. Never commit a key.

```sh
khotan auth set-key --api-url https://app.example.com --api-key khk_live_...
khotan whoami
```

Pin the repo to its organization so a stray machine-global profile cannot leak another customer's data:

```txt
# .env.khotan.local (git-ignored)
KHOTAN_API_URL='https://<workspace>.khotan.com'
KHOTAN_API_KEY='<org-scoped key>'
KHOTAN_ORG_ID='<org id>'
```

If `apps list` returns unfamiliar product names, **stop**. See [errors](/cli/errors/).

## What the CLI covers

- [Install](/cli/install/) — npx, global binary, running from source
- [Auth](/cli/auth/) — profiles, environment variables, `.env.khotan.local`, `--assert-org`
- [Workspace](/cli/workspace/) — checkout freshness, org monorepo layout, and `khotan status`
- [Output](/cli/output/) — `--json`, stdout vs stderr
- [Safety](/cli/safety/) — read, write, destructive, secret
- [Errors](/cli/errors/) — `org_mismatch`, `confirmation_required`, and the rest
- [Commands](/cli/commands/) — catalog-generated reference
- [Agents](/cli/agents/) — how to read these docs from Claude Code, Cursor, or any coding agent

`khotan help` and `khotan <command> --help` are authoritative. If a docs page and the CLI disagree, trust the CLI.