Skip to main content
The CLI API lives at https://api.getkato.io/cli/v1. It powers the Kato 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 to check recordId, then list 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 and choose the returned recordId.
  2. Call List project environments for that record. Use an existing environment name exactly as returned.
  3. Call Pull environment variables 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 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.