> api keys and auth

Grok CLI needs an xAI API key, supplied one of four ways in priority order: the --api-key flag, the GROK_API_KEY environment variable, a .env file in the project, or apiKey in ~/.grok/user-settings.json. Keys are created at console.x.ai and start with the prefix xai-.

// api keys and auth

4 commands
Set your Grok API key with an environment variable
$ export GROK_API_KEY=xai-your-key
Pass the API key as a command-line flag
$ grok --api-key xai-your-key
Load the API key from a .env file
$ cp .env.example .env
Store the API key in user settings
$ ~/.grok/user-settings.json

// faq

Where do I get a Grok API key?

Sign up at console.x.ai, add a payment method, then open API Keys and click Create API Key. The secret (an xai-... string) is shown only once, so copy it immediately. Creating the key is free; usage is billed per token.

Which authentication method takes priority?

The --api-key/-k flag wins, then the GROK_API_KEY environment variable, then a project .env file, then apiKey in ~/.grok/user-settings.json. Use the env var or settings file for everyday work and the flag only to override for a single run.

Is it safe to put my key in user-settings.json?

It is stored in plaintext at ~/.grok/user-settings.json, readable by anything running as your user, so treat that file like any secret and do not sync it in a public dotfiles repo. On shared machines the environment variable is often preferable, and a key in .env must be gitignored.

Why is my API key being ignored?

A common cause is a JSON syntax error in ~/.grok/user-settings.json — a trailing comma or missing quote — which makes the CLI silently skip the file. Another is precedence: an exported GROK_API_KEY or a --api-key flag overrides the file. Validate the JSON and check your environment.

// categories

> view all grok cli commands