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

# CLI configuration and CI

> Configure credentials, run CI builds, and load environment variables in Node.js.

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:

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

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

```bash theme={null}
npm install @getkato/cli
```

Then load variables before initializing services that need them:

```js theme={null}
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](/api-reference/quickstart) for those resources.

## Inspect configuration without printing values

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


## Related topics

- [Kato CLI](/documentation/cli.md)
- [Connect related records](/documentation/data/relationships.md)
- [CLI API](/api-reference/cli/overview.md)
- [Build an automation](/documentation/build-an-automation.md)
- [Choose what to track](/documentation/data/objects.md)