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

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

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.