Kato CLI

The @getkato/cli package connects a local project to environment variables stored in Kato. It requires Node.js 20 or later.

Install and authenticate

Install the package in your project:

npm install --save-dev @getkato/cli
npx kato login

In Kato, open a project record's .env tab and choose CLI. Create a token with env:read to pull variables; include env:write if you also need to push. Copy the token when shown and paste it into the login prompt. API key creation requires Pro.

Environment access requires the key owner to be a workspace owner or admin. This role is checked when variables are read or written. A token created from a project's .env tab is pinned to that project.

Login checks the token and stores credentials in ~/.kato/credentials.json with owner-only file permissions. For CI, use KATO_TOKEN instead of an interactive login.

Without a local installation, the one-off command is npx @getkato/cli login. Use npx kato only after installing the Kato package in your project.

Link your working directory

npx kato link
npx kato whoami

Choose an accessible project. Or set KATO_PROJECT_ID to the project record ID and link directly:

npx kato link --project "$KATO_PROJECT_ID" --env development

This writes .kato.json in the current directory. It stores the project reference, default environment, and optionally the API URL; it contains no environment values or bearer token and can be committed.

The CLI finds .kato.json in the current directory or its ancestors. Command flags override the linked project and environment. If no environment is configured, it uses development.

Run with environment variables

npx kato env run -- npm run dev

The CLI fetches the environment and starts your command with those variables. It does not write an env file. Variables already present in your shell take precedence over remote values. The child command's exit status is propagated.

Choose another environment explicitly:

npx kato env run --env staging -- npm run build

The selected environment must exist in the Kato project.

Pull to a file

npx kato env pull --out .env.local

The default output is .env. An existing file requires --force to overwrite. Even with --force, the CLI refuses to overwrite a Git-tracked file.

Keep generated env files ignored by Git. The CLI can add an ignore entry when .git is present in the current directory, but you should check ignore rules yourself when running from a nested directory or worktree.

Push local variables

npx kato env push --file .env.local

Push requires env:write. The default merges local keys into the remote environment, retaining remote keys absent from the file. The default input is .env.

--replace makes the remote environment match the file and removes remote keys absent from it:

npx kato env push --file .env.local --env staging --replace

Push prompts for confirmation. Review the target project, environment, and whether you chose merge or replace before confirming. The CLI currently has no --yes flag for unattended pushes.

Command reference

Environment commands accept --project, --env, and --api-url. env diff exits 1 when differences exist; errors also exit 1, so inspect the output to distinguish them.

Logout does not revoke a server-side key or clear a KATO_TOKEN already set in your shell. Revoke unused tokens in Kato. See CLI configuration and CI for precedence and automation.