> ## 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.

# Kato CLI

> Install the CLI and manage your project environment variables from the terminal.

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:

```bash theme={null}
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

```bash theme={null}
npx kato link
npx kato whoami
```

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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
npx kato env run --env staging -- npm run build
```

The selected environment must exist in the Kato project.

## Pull to a file

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

| Command                     | Behavior                                                         |
| --------------------------- | ---------------------------------------------------------------- |
| `kato login`                | Validate and store a token; accepts `--api-url`                  |
| `kato logout`               | Clear locally stored credentials                                 |
| `kato link`                 | Select a project; accepts `--project` and `--env`                |
| `kato whoami`               | Show workspace, scopes, and linked project details               |
| `kato env pull`             | Write variables; `--out` and `--force`                           |
| `kato env run -- <command>` | Run a child process with variables                               |
| `kato env push`             | Merge variables; `--file` and optional `--replace`               |
| `kato env list`             | List key names without values; optional `--json`                 |
| `kato env diff`             | Compare remote variables with `--file`; report changed key names |

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](/documentation/cli-configuration) for precedence and automation.


## Related topics

- [CLI API](/api-reference/cli/overview.md)
- [Developer quickstart](/api-reference/quickstart.md)
- [Integrations](/integrations/overview.md)
- [Changelog](/changelog.md)
- [CLI configuration and CI](/documentation/cli-configuration.md)