# Khotan Docs

> Khotan is an agent-native workspace for apps, pipelines, databases, files, and context. The CLI is a thin adapter over the `/api/v1` surface.

When using the khotan CLI:

- `khotan help` and `khotan <command> --help` are authoritative. Never invent flags.
- Check npm for the current `@khotan/cli` version rather than a memorized one.
- Assert the organization before trusting any output. Stop if `apps list` returns unfamiliar data.
- Destructive commands refuse non-interactively unless you pass `--yes`.
- Never commit an API key.
- Add `--json` for machine output. Results go to stdout; diagnostics go to stderr.

When calling the HTTP API directly:

- `/api/v1` is the surface the CLI wraps; the CLI adds no capability the API lacks.
- The base URL is always `https://app.khotan.com`. There is no per-workspace API host: a key carries its organization and no operation reads the request host.
- Authenticate with an organization-scoped API key: `Authorization: Bearer <key>`.
- Generate clients from the OpenAPI document, not from these pages. Use the published copy on this site, or `https://app.khotan.com/api/v1/openapi.json` for a specific deployment.

Prefer the Markdown links below, /docs.json, or /search.json?q= over scraping HTML.

The site is static HTML with no client-side application runtime.

## Home

- [Khotan](https://docs.khotan.com/): Let the agents build. The Khotan CLI is the first-party adapter over the /api/v1 surface.
  - Markdown: https://docs.khotan.com/index.md

## Basics

- [Basics](https://docs.khotan.com/basics/): Why Khotan exists, and how the CLI relates to the HTTP API.
  - Markdown: https://docs.khotan.com/basics/index.md
- [Concepts](https://docs.khotan.com/basics/concepts/): Organization, workspace layout, keys, and how the CLI relates to /api/v1.
  - Markdown: https://docs.khotan.com/basics/concepts/index.md
- [FAQ](https://docs.khotan.com/basics/faq/): Short answers about the workspace, the CLI, and the HTTP API.
  - Markdown: https://docs.khotan.com/basics/faq/index.md
- [Projects](https://docs.khotan.com/basics/projects/): What a project is, how its spec is written, how an OpenSpec change becomes an issue, and how apps report metrics.
  - Markdown: https://docs.khotan.com/basics/projects/index.md

## CLI

- [CLI](https://docs.khotan.com/cli/): Install, authenticate, and operate Khotan from the command line.
  - Markdown: https://docs.khotan.com/cli/index.md
- [Agents](https://docs.khotan.com/cli/agents/): How a coding agent should read Khotan CLI documentation. Fetch Markdown, do not scrape HTML.
  - Markdown: https://docs.khotan.com/cli/agents/index.md
- [Auth](https://docs.khotan.com/cli/auth/): Organization-scoped API keys, profiles, .env.khotan.local, and fail-closed org isolation.
  - Markdown: https://docs.khotan.com/cli/auth/index.md
- [Commands](https://docs.khotan.com/cli/commands/): Catalog-derived CLI command reference. Trust khotan help if anything disagrees.
  - Markdown: https://docs.khotan.com/cli/commands/index.md
- [Apps](https://docs.khotan.com/cli/commands/apps/): CLI commands for Khotan apps.
  - Markdown: https://docs.khotan.com/cli/commands/apps/index.md
- [Storage buckets](https://docs.khotan.com/cli/commands/buckets/): CLI commands for Khotan storage buckets.
  - Markdown: https://docs.khotan.com/cli/commands/buckets/index.md
- [Context documents](https://docs.khotan.com/cli/commands/context/): CLI commands for Khotan context documents.
  - Markdown: https://docs.khotan.com/cli/commands/context/index.md
- [Databases](https://docs.khotan.com/cli/commands/databases/): CLI commands for Khotan databases and database branches.
  - Markdown: https://docs.khotan.com/cli/commands/databases/index.md
- [Feedback](https://docs.khotan.com/cli/commands/feedback/): CLI commands for Khotan feedback to the Khotan team.
  - Markdown: https://docs.khotan.com/cli/commands/feedback/index.md
- [Files](https://docs.khotan.com/cli/commands/files/): CLI commands for Khotan files.
  - Markdown: https://docs.khotan.com/cli/commands/files/index.md
- [Folders](https://docs.khotan.com/cli/commands/folders/): CLI commands for Khotan folders.
  - Markdown: https://docs.khotan.com/cli/commands/folders/index.md
- [Integrations](https://docs.khotan.com/cli/commands/integrations/): CLI commands for Khotan integrations.
  - Markdown: https://docs.khotan.com/cli/commands/integrations/index.md
- [Organization](https://docs.khotan.com/cli/commands/organization/): CLI commands for Khotan organization brand.
  - Markdown: https://docs.khotan.com/cli/commands/organization/index.md
- [Pipelines](https://docs.khotan.com/cli/commands/pipelines/): CLI commands for Khotan pipelines.
  - Markdown: https://docs.khotan.com/cli/commands/pipelines/index.md
- [Projects](https://docs.khotan.com/cli/commands/projects/): CLI commands for Khotan projects.
  - Markdown: https://docs.khotan.com/cli/commands/projects/index.md
- [Redis (KV)](https://docs.khotan.com/cli/commands/redis/): CLI commands for Khotan Redis (KV) databases.
  - Markdown: https://docs.khotan.com/cli/commands/redis/index.md
- [Implementation traces](https://docs.khotan.com/cli/commands/traces/): CLI commands for Khotan implementation traces.
  - Markdown: https://docs.khotan.com/cli/commands/traces/index.md
- [Errors](https://docs.khotan.com/cli/errors/): Lookup table for CLI error codes. Do not invent flags when one of these appears.
  - Markdown: https://docs.khotan.com/cli/errors/index.md
- [Install](https://docs.khotan.com/cli/install/): Install or invoke the Khotan CLI with standard npm tooling.
  - Markdown: https://docs.khotan.com/cli/install/index.md
- [OpenSpec](https://docs.khotan.com/cli/openspec/): File a change directory as an issue, and commit spec edits from a JSON document.
  - Markdown: https://docs.khotan.com/cli/openspec/index.md
- [Output](https://docs.khotan.com/cli/output/): Human tables by default, --json on stdout, diagnostics on stderr.
  - Markdown: https://docs.khotan.com/cli/output/index.md
- [Safety](https://docs.khotan.com/cli/safety/): read, write, destructive, and secret capability classes, and when to pass --yes.
  - Markdown: https://docs.khotan.com/cli/safety/index.md
- [Workspace](https://docs.khotan.com/cli/workspace/): Organization monorepo layout, khotan status, and WORKSPACE.md.
  - Markdown: https://docs.khotan.com/cli/workspace/index.md

## HTTP API

- [HTTP API](https://docs.khotan.com/api/): Generated reference for the Khotan /api/v1 REST surface (v1.0.0), the API the CLI wraps.
  - Markdown: https://docs.khotan.com/api/index.md
- [AI capture](https://docs.khotan.com/api/ai-capture/): HTTP API reference for Khotan ai capture (2 operations).
  - Markdown: https://docs.khotan.com/api/ai-capture/index.md
- [Apps](https://docs.khotan.com/api/apps/): HTTP API reference for Khotan apps (29 operations).
  - Markdown: https://docs.khotan.com/api/apps/index.md
- [Authentication](https://docs.khotan.com/api/auth/): How API keys are obtained, scoped, sent, and kept safe.
  - Markdown: https://docs.khotan.com/api/auth/index.md
- [Buckets](https://docs.khotan.com/api/buckets/): HTTP API reference for Khotan buckets (7 operations).
  - Markdown: https://docs.khotan.com/api/buckets/index.md
- [Context](https://docs.khotan.com/api/context/): HTTP API reference for Khotan context (16 operations).
  - Markdown: https://docs.khotan.com/api/context/index.md
- [Conventions](https://docs.khotan.com/api/conventions/): Errors, retries, rate limits, versioning, and the boundaries the API deliberately holds.
  - Markdown: https://docs.khotan.com/api/conventions/index.md
- [Databases](https://docs.khotan.com/api/databases/): HTTP API reference for Khotan databases (16 operations).
  - Markdown: https://docs.khotan.com/api/databases/index.md
- [Feedback](https://docs.khotan.com/api/feedback/): HTTP API reference for Khotan feedback (1 operation).
  - Markdown: https://docs.khotan.com/api/feedback/index.md
- [Files](https://docs.khotan.com/api/files/): HTTP API reference for Khotan files (9 operations).
  - Markdown: https://docs.khotan.com/api/files/index.md
- [Folders](https://docs.khotan.com/api/folders/): HTTP API reference for Khotan folders (4 operations).
  - Markdown: https://docs.khotan.com/api/folders/index.md
- [Implementation traces](https://docs.khotan.com/api/implementation-traces/): HTTP API reference for Khotan implementation traces (1 operation).
  - Markdown: https://docs.khotan.com/api/implementation-traces/index.md
- [Inbox](https://docs.khotan.com/api/inbox/): HTTP API reference for Khotan inbox (7 operations).
  - Markdown: https://docs.khotan.com/api/inbox/index.md
- [Integrations](https://docs.khotan.com/api/integrations/): HTTP API reference for Khotan integrations (6 operations).
  - Markdown: https://docs.khotan.com/api/integrations/index.md
- [Organization](https://docs.khotan.com/api/organization/): HTTP API reference for Khotan organization (3 operations).
  - Markdown: https://docs.khotan.com/api/organization/index.md
- [Pipelines](https://docs.khotan.com/api/pipelines/): HTTP API reference for Khotan pipelines (27 operations).
  - Markdown: https://docs.khotan.com/api/pipelines/index.md
- [Projects](https://docs.khotan.com/api/projects/): HTTP API reference for Khotan projects (26 operations).
  - Markdown: https://docs.khotan.com/api/projects/index.md
- [Quickstart](https://docs.khotan.com/api/quickstart/): Go from no credential to a working API call with nothing installed but curl.
  - Markdown: https://docs.khotan.com/api/quickstart/index.md
- [Redis Databases](https://docs.khotan.com/api/redis-databases/): HTTP API reference for Khotan redis databases (6 operations).
  - Markdown: https://docs.khotan.com/api/redis-databases/index.md
- [Reporting metrics](https://docs.khotan.com/api/reporting-metrics/): Report a project's KPIs from an app's cron job, safely retried and never double-counted.
  - Markdown: https://docs.khotan.com/api/reporting-metrics/index.md
- [SQLite Databases](https://docs.khotan.com/api/sqlite-databases/): HTTP API reference for Khotan sqlite databases (5 operations).
  - Markdown: https://docs.khotan.com/api/sqlite-databases/index.md

## Machine-readable entrypoints

- [docs.json](https://docs.khotan.com/docs.json): manifest with per-page headings.
- [llms-full.txt](https://docs.khotan.com/llms-full.txt): every page in one request.
- [CLI llms.txt](https://docs.khotan.com/cli/llms.txt): CLI pages only.
- [API llms.txt](https://docs.khotan.com/api/llms.txt): HTTP API pages only.
- [search.json](https://docs.khotan.com/search.json?q=): ranked search; omit `q` for the full index.
- [sitemap.xml](https://docs.khotan.com/sitemap.xml): every HTML page.
- [openapi.json](https://docs.khotan.com/openapi.json): the `/api/v1` document; generate clients from this.