> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI API

> Project discovery and environment-variable access for developer keys.

The CLI API lives at `https://api.getkato.io/cli/v1`. It powers the [Kato CLI](/documentation/cli); use this reference when implementing a compatible client or diagnosing an HTTP response.

## Credentials and project access

Send a developer access key as `Authorization: Bearer $KATO_API_KEY`. The key selects one workspace. A key can also be pinned to one project record: [inspect credentials](/api-reference/cli/whoami) to check `recordId`, then [list projects](/api-reference/cli/projects) to find a usable ID.

Environment operations require the key owner's **current owner or admin membership**, as well as `env:read` or `env:write`. A write scope includes read access. A key pinned to a project cannot access another project's environments. Raycast OAuth tokens are not accepted.

## Read an environment

1. Call [List CLI projects](/api-reference/cli/projects) and choose the returned `recordId`.
2. Call [List project environments](/api-reference/cli/environments) for that record. Use an existing environment name exactly as returned.
3. Call [Pull environment variables](/api-reference/cli/pull) with both `recordId` and `env`.
4. Consume either the structured `vars` map or the formatted `dotenv` string. Both contain decrypted secrets; keep response bodies out of logs and client-side bundles.

## Change variables

[Push environment variables](/api-reference/cli/push) accepts a `vars` map. With `mode: "merge"`, supplied keys are added or changed and omitted keys remain. With `mode: "replace"`, the supplied map becomes the entire environment; omitted keys are removed. An empty replacement removes every variable.

Neither pull nor push creates a missing project or environment. Set up the project environment in Kato first. Inspect the returned `summary.added`, `summary.changed`, `summary.removed`, and `version` fields after a push before continuing a deployment.

## Responses and errors

These endpoints do not share the general developer API's `data` wrapper. Project and environment discovery return bare arrays; identity, pull, and push return top-level objects. Follow the example on each endpoint page.

The limit is **120 requests per minute per key**. A `429` body includes `retryAfterMs`; wait that many milliseconds before retrying. Missing scopes or admin access return `403`; an unknown project, incompatible project pin, or missing environment returns `404`. Authentication and validation failures may have different error structures, so check the status before reading the body.


## Related topics

- [All endpoints](/api-reference/endpoints.md)
- [Inspect CLI credentials](/api-reference/cli/whoami.md)
- [List CLI projects](/api-reference/cli/projects.md)
- [List project environments](/api-reference/cli/environments.md)
- [Push environment variables](/api-reference/cli/push.md)