CLI configuration and CI

Use the CLI in a local shell, a build job, or a Node.js server process. Keep the token on the server or build runner; never include it in browser code or client bundles.

Configuration precedence

Setting	Highest precedence first
Token	`KATO_TOKEN` → `~/.kato/credentials.json`
Project	`--project` → nearest `.kato.json`
Environment	`--env` → `.kato.json` `env` → `development`
API URL for env commands	`--api-url` → `.kato.json` `apiUrl` → `KATO_API_URL` → saved credentials → `https://api.getkato.io`

Login, link, and whoami use the explicit API URL, then KATO_API_URL, saved credentials, and the default. They do not use an API URL from the linked project. Set API URLs to an origin such as https://api.getkato.io, without /v1 or /cli/v1; the CLI appends its route prefix. For env run and loadEnv({ assign: true }), existing process environment variables win over values fetched from Kato.

Run in CI

Install the CLI in your project and commit the package lockfile. Store a project-scoped, read-only token in your CI provider’s secret store, and expose it to the build step as KATO_TOKEN. With Node.js 20+ available and a committed .kato.json pointing to your project, run:

npm ci
npx kato env run --env production -- npm run build

Your dependency installation must include @getkato/cli. If it is a dev dependency, do not omit dev dependencies before running the build step. No login step is needed. The build command receives the variables and its exit status is propagated. Keep KATO_TOKEN out of command output and build artifacts. The production environment must already exist. Without a committed link file, supply a project record ID through a non-secret CI variable:

npx kato env run \
  --project "$KATO_PROJECT_ID" \
  --env production \
  -- npm run build

This example reads variables; it does not change them. env push is interactive and has no unattended confirmation flag.

Load variables in Node.js

Install @getkato/cli as a runtime dependency if you use it in your server process:

npm install @getkato/cli

Then load variables before initializing services that need them:

import { loadEnv } from "@getkato/cli";

await loadEnv({
  env: "production",
  assign: true,
});

// Initialize server-side clients after the variables are loaded.

loadEnv uses KATO_TOKEN or saved credentials and the linked project unless you pass project. It also accepts apiUrl. With assign: true, it fills only undefined entries in process.env. Without assign, it returns a map of strings and does not modify the process environment. The package is an environment-variable client, not a general records/tasks SDK. Use the REST API for those resources.

Inspect configuration without printing values

npx kato whoami
npx kato env list --env staging
npx kato env diff --env staging --file .env.local

env list prints key names; --json returns an object with environment and keys. env diff compares values but reports key names only. It exits 1 for differences, so avoid treating that exit code alone as a connection failure.

Troubleshooting

Error or symptom	What to do
Not logged in	Run `npx kato login` locally, or supply `KATO_TOKEN` in CI
No project selected	Run `link` or pass `--project`
Project not found	Check the project ID and the token’s project restriction
Environment not found	Check the environment name in the project’s .env tab
Missing env scope	Create a token with `env:read` or `env:write`
Owner is not an admin	An owner or admin must own the token; current membership is checked
Local file exists	Choose another output or intentionally use `--force`
File is Git-tracked	Choose an ignored output path; `--force` does not bypass this check
Remote value seems ignored	Check for an existing variable in the shell or CI environment
Token still works after logout	`KATO_TOKEN` overrides local credentials; unset it or revoke the token
Wrong API host	Check the linked `apiUrl` as well as flags and environment variables

To change credentials, create and distribute a replacement token, verify it, then revoke the old token. Do not commit tokens, downloaded env files, or credentials files.

​Configuration precedence

​Run in CI

​Load variables in Node.js

​Inspect configuration without printing values

​Troubleshooting

Configuration precedence

Run in CI

Load variables in Node.js

Inspect configuration without printing values

Troubleshooting