Authentication - GC AI

The CLI authenticates with a GC AI API key. See API keys for the difference between personal and organization keys.

Logging in

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:

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

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

⌘I