> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# CLI authentication

> Give the CLI a root key by flag, environment variable, or stored config.

Every CLI command that calls the API needs a root key, the same one you'd send in `Authorization: Bearer`. The easiest way is to store it once with `unkey auth login`. You can also pass it with a flag or an environment variable.

## Store a key with `unkey auth login`

```bash theme={"system"}
unkey auth login
```

It asks for your root key (`Enter your root key:`) and doesn't show what you type, so the key stays out of your screen and shell history. It saves the key to `~/.unkey/config.toml`, which only your user can read. Run it again to replace the stored key. See [unkey auth login](/docs/platform/cli/auth/login) for the full reference.

The file holds the key in plain text, so treat it like the key. Keep it out of version control and off shared machines. It's best to create a root key just for the CLI, with only the permissions your scripts need. See [Root key permissions](/docs/platform/root-keys/permissions).

## Override the stored key

For one command, pass `--root-key`:

```bash theme={"system"}
unkey api keys get-key --key-id=key_1234abcd --root-key=unkey_xxx
```

For a whole shell session, set `UNKEY_ROOT_KEY`:

```bash theme={"system"}
export UNKEY_ROOT_KEY=unkey_xxx
unkey api keys get-key --key-id=key_1234abcd
```

## Which key `unkey api` uses

`unkey api` commands use the first key they find:

1. The `--root-key` flag.
2. The `UNKEY_ROOT_KEY` environment variable.
3. The `root_key` value in the config file. That's `~/.unkey/config.toml` unless you set `--config` or `UNKEY_CONFIG`.

If there's no key anywhere, the command stops before calling the API with `no root key provided`. If the API rejects the key, you get `Authentication failed: ...` and a hint to run `unkey auth login`.

## `unkey deploy` doesn't read the config file

`unkey deploy` only takes a key from `--root-key` or `UNKEY_ROOT_KEY`. It never reads `~/.unkey/config.toml`, so `unkey auth login` doesn't help it. In CI, set `UNKEY_ROOT_KEY` as a secret. Locally, export it in the shell you deploy from. See [unkey deploy](/docs/compute/cli/deploy).

## Point at a different API host

`--api-url` (or `UNKEY_API_BASE_URL`) sets the base URL for `unkey api` commands, and `unkey deploy` has `--api-base-url`. The default is `https://api.unkey.com`. You don't normally need to change it.