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

# Authentication

> Log in to the gcai CLI with an API key, and control which key and base URL each command uses.

The CLI authenticates with a GC AI API key. See [API keys](/api-reference/concepts/api-keys) for the difference between personal and organization keys.

## Logging in

```bash theme={null}
gcai auth login
```

This prints a prompt, opens **Settings → API** in your browser, and waits for you to paste a key. It verifies the key with a `ping` before saving it. Account creation is browser-only; `gcai auth signup` opens the sign-up page.

Related commands:

| Command                                  | What it does                                                                                                                                           |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `gcai auth status` (alias `gcai whoami`) | Show the active base URL, where the key came from, a masked key, and whether it is valid. Exits non-zero when unauthenticated, so it works in scripts. |
| `gcai auth logout`                       | Delete the stored credentials.                                                                                                                         |

## Where credentials live

`gcai auth login` stores your key and base URL in `~/.config/gcai/config.json` (or `$XDG_CONFIG_HOME/gcai/config.json`), created with owner-only permissions. Storing the base URL alongside the key means a key minted against a non-production environment keeps hitting the right server without re-passing `--base-url`.

## Choosing a key without logging in

You can skip the stored login for a single command with a flag or an environment variable. Each command resolves its key and base URL in this order:

1. `--api-key` / `--base-url` flags
2. `GCAI_API_KEY` / `GCAI_BASE_URL` environment variables
3. the stored login (`gcai auth login`)
4. the default base URL (`https://app.gc.ai/api/external/v1`)

```bash theme={null}
# One-off with an env var, no stored login
GCAI_API_KEY=u:gcai_… gcai projects list

# Override per command
gcai projects list --api-key u:gcai_… --base-url https://app.gc.ai/api/external/v1
```

This makes the CLI convenient in CI: set `GCAI_API_KEY` as a secret and skip `auth login` entirely.