Grok CLI

xAI console agent with a custom Guard model.

Model protocol

Claude, Kimi, Composer and Grok

Grok CLI is the console agent from xAI: repository xai-org/grok-build, command grok. A third-party address is not a workaround here but a documented feature: your own model is declared as an entry with its own address, its own key and its own protocol.

bash

curl -fsSL https://x.ai/cli/install.sh | bash

Settings live in ~/.grok/config.toml. Every custom model is one [model.<name>] entry. In it, model is the exact id sent to the server, base_url is the address, env_key names the environment variable holding the key, and api_backend picks the protocol. It has exactly three values: chat_completions by default, responses and messages.

toml

# ~/.grok/config.toml
[model.guard]
model = "claude-sonnet-5-5"
name = "Guard Claude Sonnet 5.5"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_API_KEY"
api_backend = "chat_completions"
max_completion_tokens = 8192
context_window = 1000000

toml

# ~/.grok/config.toml
[model.guard]
model = "k3"
name = "Guard Kimi K3"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_API_KEY"
api_backend = "chat_completions"
max_completion_tokens = 8192
context_window = 1048576

toml

# ~/.grok/config.toml
[model.guard]
model = "cursor-grok-4.7-high"
name = "Guard Grok 4.7"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_API_KEY"
api_backend = "chat_completions"
max_completion_tokens = 8192
context_window = 256000

toml

# ~/.grok/config.toml
[model.guard]
model = "composer-2.5"
name = "Guard Composer 2.5"
base_url = "https://api.guardrelay.ai/v1"
env_key = "GUARD_API_KEY"
api_backend = "chat_completions"
max_completion_tokens = 8192
context_window = 200000

The key goes into the variable named by env_key, or straight into the api_key field of the same entry. The client takes api_key first, then the variable from env_key, and only then its own xAI sign-in and the shared XAI_API_KEY variable.

A one-off run: grok -p "hello" -m guard. Inside a session the model is switched with /model guard, grok models lists what is available, and a permanent default is set by a separate [models] entry with a default field.

GLM 5.3 in Grok CLI

Install Grok CLI

Install official Grok Build from the xAI guide. Use the first block on macOS/Linux/Git Bash, or the second on Windows PowerShell.

bash

curl -fsSL https://x.ai/cli/install.sh | bash
grok --version

powershell

irm https://x.ai/cli/install.ps1 | iex
grok --version

Get a Guard key

Get a universal gd-… key from the direct API link in @guardapi and choose an API package. Do not put the key in a project, repository, task prompt, or screenshot. Balance and usage are available in your Guard account.

Create two custom models

Open ~/.grok/config.toml (Windows: %USERPROFILE%\.grok\config.toml). context_window = 200000 below is the verified profile's client-side budget, not a published GLM limit. max_completion_tokens = 4096 is a bounded example for one response.

toml

[models]
default = "glm-5.3"

[model."glm-5.3"]
model = "glm-5.3"
base_url = "https://api.guardrelay.ai/glm/v1"
name = "GLM 5.3"
env_key = "GUARD_GLM_API_KEY"
api_backend = "responses"
max_completion_tokens = 4096
context_window = 200000
supports_backend_search = false
stream_tool_calls = true

[model."glm-5.3-flash"]
model = "glm-5.3-flash"
base_url = "https://api.guardrelay.ai/glm/v1"
name = "GLM 5.3 Flash"
env_key = "GUARD_GLM_API_KEY"
api_backend = "responses"
max_completion_tokens = 4096
context_window = 200000
supports_backend_search = false
stream_tool_calls = true

macOS / Linux: enter the key at the hidden prompt. The variable applies only to this terminal and the client started from it.

{
unset GUARD_GLM_API_KEY
until [ -n "${GUARD_GLM_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_GLM_API_KEY || break; printf "\n"; done
export GUARD_GLM_API_KEY

grok -m glm-5.3
}

Windows PowerShell: run these commands in the same window that starts the client. Set the key again after opening a new PowerShell window.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_GLM_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password

grok -m glm-5.3

Check and continue

bash

grok --model glm-5.3 --disable-web-search --single "Reply with exactly GLM_OK and remember PINE"
grok --continue --model glm-5.3 --disable-web-search --single "What word were you asked to remember?"

Run grok -m glm-5.3 for an interactive conversation; grok -c continues the last conversation in the current folder. supports_backend_search = false and --disable-web-search do not attach a separate search service to GLM.

Models and confirmed capabilities

Model ID	When to use it
`glm-5.3`	Default model; text and coding tasks.
`glm-5.3-flash`	Fast model; at API level it accepts PNG and PDF through all three protocols, and MP4 through Chat Completions only.

Responses, local file/shell tools, and --continue in the same folder are confirmed.
The client itself executes file, edit, and terminal tools. This profile does not connect Z.AI tools or MCP automatically.
This version was checked with text tasks; its attachment button was not checked. Flash capability at API level does not prove that this particular UI can send a file.
The profile uses OpenAI Responses. The GLM server prompt is off by default for ordinary API access; client setup does not enable it.
Native TXT, DOCX, and XLSX are outside the confirmed GLM contract. Use PDF for documents, or PNG with glm-5.3-flash for images.

If the connection fails

Symptom	What to check
`401 invalid_api_key`	The client received the complete active `gd-…` key; the variable is set in the same process that starts the client.
`404 model_not_found`	The model ID is exactly `glm-5.3` or `glm-5.3-flash`; old GLM IDs, aliases, Turbo, and FlashX are unsupported.
`404` or incorrect path	Base URL is `https://api.guardrelay.ai/glm/v1`. The client appends `/responses`; do not add it twice.
`400 invalid_request`	The documented API format is selected; reasoning, temperature, MCP, or other unconfirmed fields were not copied from an older profile.
`402 insufficient_balance`	Check available balance and unfinished reservations in your Guard account.
`grok models` does not show GLM	Check exact headings `[model."glm-5.3"]`, `[models] default`, and the file under the current user's `GROK_HOME`.
The client attempts xAI login	Check `env_key = "GUARD_GLM_API_KEY"`, `api_backend = "responses"`, and selection of custom model `glm-5.3`.

Gemini in Grok CLI

Install Grok CLI

Install official Grok Build from the xAI guide. Use the first block on macOS/Linux/Git Bash, or the second on Windows PowerShell.

bash

curl -fsSL https://x.ai/cli/install.sh | bash
grok --version

powershell

irm https://x.ai/cli/install.ps1 | iex
grok --version

Get a Guard key

Add the Gemini models

Open ~/.grok/config.toml (Windows: %USERPROFILE%\.grok\config.toml). context_window = 1048576 below is the model window from the table and the client-side budget of Grok CLI; max_completion_tokens = 4096 is a bounded example for one response.

toml

[models]
default = "gemini-4-argon"

[model."gemini-4-argon"]
model = "gemini-4-argon"
base_url = "https://api.guardrelay.ai/v1"
name = "Gemini 4 Argon"
env_key = "GUARD_GEMINI_API_KEY"
api_backend = "responses"
max_completion_tokens = 4096
context_window = 1048576
supports_backend_search = false
stream_tool_calls = true

[model."gemini-3.8-flash"]
model = "gemini-3.8-flash"
base_url = "https://api.guardrelay.ai/v1"
name = "Gemini 3.8 Flash"
env_key = "GUARD_GEMINI_API_KEY"
api_backend = "responses"
max_completion_tokens = 4096
context_window = 1048576
supports_backend_search = false
stream_tool_calls = true

macOS / Linux: enter the key at the hidden prompt. The variable applies only to this terminal and the client started from it.

{
unset GUARD_GEMINI_API_KEY
until [ -n "${GUARD_GEMINI_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_GEMINI_API_KEY || break; printf "\n"; done
export GUARD_GEMINI_API_KEY
grok -m gemini-4-argon
}

Windows PowerShell: run these commands in the same window that starts the client. Set the key again after opening a new PowerShell window.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_GEMINI_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password
grok -m gemini-4-argon

Check and continue

bash

grok --model gemini-4-argon --disable-web-search --single "Reply with exactly GUARD_GEMINI_OK and remember PINE"
grok --continue --model gemini-4-argon --disable-web-search --single "What word were you asked to remember?"

Run grok -m gemini-4-argon for an interactive conversation; grok -c continues the last conversation in the current folder. supports_backend_search = false and --disable-web-search do not attach a separate xAI search service to Gemini.

Gemini models and capabilities

Model ID	Input and window
`gemini-4-argon`	Text, images, PDF; 1,048,576-token window, shared by input and answer.
`gemini-3.8-flash`	Text, images, PDF; 1,048,576-token window for input.

Grok CLI itself executes the local file and shell tools; --continue continues the conversation in the same folder.
The Guard catalog takes text, images, and PDF as input and returns text. How to send a file or an image depends on the client's interface; this guide does not describe attachments.
The profile uses OpenAI Responses. The server prompt is a separate setting of the Gemini family: it applies only when the key has the entitlement and the option is on; client setup does not enable it.

If the connection fails

Symptom	What to check
`401 invalid_api_key`	The client received the complete active `gd-…` key; the variable is set in the same process that starts the client.
`404 model_not_found`	The model ID is an exact ID from the table above or the short name `gemini`; other spellings are unsupported.
`404` or incorrect path	Base URL is `https://api.guardrelay.ai/v1`. The client appends `/responses`; do not add it twice.
`400 invalid_request`	The documented API format is selected; extra settings from an older profile were not copied: reasoning, temperature, MCP, and others.
`402 insufficient_credit`	Check available balance and unfinished reservations in your Guard account.
`grok models` does not show Gemini	Check exact headings `[model."gemini-4-argon"]`, `[models] default`, and the file under the current user's `GROK_HOME`.
The client attempts xAI login	Check `env_key = "GUARD_GEMINI_API_KEY"`, `api_backend = "responses"`, and selection of custom model `gemini-4-argon`.

Muse in Grok CLI

Install Grok CLI

Install official Grok Build from the xAI guide. Use the first block on macOS/Linux/Git Bash, or the second on Windows PowerShell.

bash

curl -fsSL https://x.ai/cli/install.sh | bash
grok --version

powershell

irm https://x.ai/cli/install.ps1 | iex
grok --version

Get a Guard key

Add the Muse models

toml

[models]
default = "muse-wonder-1.0"

[model."muse-wonder-1.0"]
model = "muse-wonder-1.0"
base_url = "https://api.guardrelay.ai/v1"
name = "Muse Wonder 1.0"
env_key = "GUARD_MUSE_API_KEY"
api_backend = "responses"
max_completion_tokens = 4096
context_window = 1048576
supports_backend_search = false
stream_tool_calls = true

[model."muse-spark-1.3"]
model = "muse-spark-1.3"
base_url = "https://api.guardrelay.ai/v1"
name = "Muse Spark 1.3"
env_key = "GUARD_MUSE_API_KEY"
api_backend = "responses"
max_completion_tokens = 4096
context_window = 1048576
supports_backend_search = false
stream_tool_calls = true

[model."muse-spark-1.2"]
model = "muse-spark-1.2"
base_url = "https://api.guardrelay.ai/v1"
name = "Muse Spark 1.2"
env_key = "GUARD_MUSE_API_KEY"
api_backend = "responses"
max_completion_tokens = 4096
context_window = 1048576
supports_backend_search = false
stream_tool_calls = true

macOS / Linux: enter the key at the hidden prompt. The variable applies only to this terminal and the client started from it.

{
unset GUARD_MUSE_API_KEY
until [ -n "${GUARD_MUSE_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_MUSE_API_KEY || break; printf "\n"; done
export GUARD_MUSE_API_KEY
grok -m muse-wonder-1.0
}

Windows PowerShell: run these commands in the same window that starts the client. Set the key again after opening a new PowerShell window.

powershell

$guardKey = Read-Host "Guard API key" -AsSecureString
$env:GUARD_MUSE_API_KEY = [System.Net.NetworkCredential]::new("", $guardKey).Password
grok -m muse-wonder-1.0

Check and continue

bash

grok --model muse-wonder-1.0 --disable-web-search --single "Reply with exactly GUARD_MUSE_OK and remember PINE"
grok --continue --model muse-wonder-1.0 --disable-web-search --single "What word were you asked to remember?"

Run grok -m muse-wonder-1.0 for an interactive conversation; grok -c continues the last conversation in the current folder. supports_backend_search = false and --disable-web-search do not attach a separate xAI search service to Muse.

Muse models and capabilities

Model ID	Input and window
`muse-wonder-1.0`	Text, images, PDF; 1,048,576-token window.
`muse-spark-1.3`	Text, images, PDF; 1,048,576-token window.
`muse-spark-1.2`	Text, images, PDF; 1,048,576-token window.

Grok CLI itself executes the local file and shell tools; --continue continues the conversation in the same folder.
The Guard catalog takes text, images, and PDF as input and returns text. How to send a file or an image depends on the client's interface; this guide does not describe attachments.
The profile uses OpenAI Responses. The server prompt is a separate setting of the Muse family: it applies only when the key has the entitlement and the option is on; client setup does not enable it.

If the connection fails

Symptom	What to check
`401 invalid_api_key`	The client received the complete active `gd-…` key; the variable is set in the same process that starts the client.
`404 model_not_found`	The model ID is an exact ID from the table above or the short name `muse`; other spellings are unsupported.
`404` or incorrect path	Base URL is `https://api.guardrelay.ai/v1`. The client appends `/responses`; do not add it twice.
`400 invalid_request`	The documented API format is selected; extra settings from an older profile were not copied: reasoning, temperature, MCP, and others.
`402 insufficient_credit`	Check available balance and unfinished reservations in your Guard account.
`grok models` does not show Muse	Check exact headings `[model."muse-wonder-1.0"]`, `[models] default`, and the file under the current user's `GROK_HOME`.
The client attempts xAI login	Check `env_key = "GUARD_MUSE_API_KEY"`, `api_backend = "responses"`, and selection of custom model `muse-wonder-1.0`.

Install Grok CLI

Install the official Grok Build (grok) using xAI's instructions. Use the first command on macOS, Linux, or Git Bash; use the second in Windows PowerShell. Check grok --version.

bash

curl -fsSL https://x.ai/cli/install.sh | bash
grok --version

powershell

irm https://x.ai/cli/install.ps1 | iex
grok --version

Get a Guard key

Open @guardapi → Categories → API, choose a package, and save the gd-… key. A Grok custom model needs no separate xAI account login: the Guard key is supplied through GUARD_API_KEY.

Create a custom model

Open ~/.grok/config.toml (Windows: %USERPROFILE%\.grok\config.toml). If it does not exist, create the .grok folder and config.toml file in your home directory.
Add [model.guard-codex]. Keep existing [model.*], [models], and other settings; do not create a second [model.guard-codex] table.
Set model = "gpt-6-astra", base_url = "https://api.guardrelay.ai/codex/v1", env_key = "GUARD_API_KEY", and api_backend = "responses". This calls POST /responses; do not append /responses to the Base URL.
Set GUARD_API_KEY in the terminal that launches grok. If the same model table also has api_key, it takes precedence over env_key; remove the old value when switching to the variable.

toml

# Add to ~/.grok/config.toml
[model.guard-codex]
model = "gpt-6-astra"
name = "GUARD API · GPT-6 Astra"
base_url = "https://api.guardrelay.ai/codex/v1"
env_key = "GUARD_API_KEY"
api_backend = "responses"
context_window = 872000

For gpt-6-astra, you can choose its supported max reasoning level on launch. context_window is a Grok budget from catalog metadata, not a hard request limit. This profile uses Responses, so do not add the Chat field max_completion_tokens. If the client sends max_output_tokens, Guard accepts and preserves it, but managed Codex does not guarantee hard truncation; billing follows actual tokens and the key's money rules.

The latest saved Guard native catalog declares these maximum-window values for client-side budgeting. They are not verified hard input caps; the client may compact history sooner. In the Guard connection, all seven models accept and preserve max_output_tokens (Responses), max_completion_tokens (Chat), and max_tokens (Messages) as advisory, without guaranteeing a hard managed Codex output limit; billing follows actual tokens and the key's money rules.

Model ID	Context value for client setup
`gpt-6-astra`	`872000`
`gpt-6.1-sol`	`872000`
`gpt-6-sol`	`872000`
`gpt-6-luna`	`872000`
`gpt-5.6-sol`	`872000`
`gpt-5.6-terra`	`872000`
`gpt-5.6-luna`	`872000`

Send the first request

macOS / Linux: the hidden prompt keeps the key out of shell command history. The variable applies to this terminal only. Launching without -p opens an interactive chat where you can ask the next question. The last line of the block, grok -c, continues the latest conversation in the same folder.

bash

{
unset GUARD_API_KEY
until [ -n "${GUARD_API_KEY-}" ]; do printf "Guard API key: "; read -r -s GUARD_API_KEY || break; printf "\n"; done
export GUARD_API_KEY
grok -p "Reply with exactly OK" -m guard-codex --reasoning-effort max
grok -c
}

Windows PowerShell:

powershell

$secret = Read-Host "Guard API key" -AsSecureString
$env:GUARD_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
grok -p "Reply with exactly OK" -m guard-codex --reasoning-effort max
grok -c

For a new interactive session, run grok -m guard-codex; to continue the latest conversation in the same folder, run grok -c. grok models lists available local names, including guard-codex.

If connection fails

Symptom	Check
`grok models` does not show `guard-codex`	`[model.guard-codex]` exists in `~/.grok/config.toml`, the file is saved, and TOML syntax is valid.
`401`	`GUARD_API_KEY` is set in the current terminal, and an old `api_key` in the model table is not overriding it.
`404` or wrong API	Base URL ends in `/codex/v1`, `api_backend` is `responses`, and exact ID `gpt-6-astra` is selected.
`402`	Check the key balance and limits in your Guard account.

Grok CLI

Claude, Kimi, Composer and Grok

GLM 5.3 in Grok CLI

Install Grok CLI

Get a Guard key

Create two custom models

Check and continue

Models and confirmed capabilities

If the connection fails

Gemini in Grok CLI

Install Grok CLI

Get a Guard key

Add the Gemini models

Check and continue

Gemini models and capabilities

If the connection fails

Muse in Grok CLI

Install Grok CLI

Get a Guard key

Add the Muse models

Check and continue

Muse models and capabilities

If the connection fails

Install Grok CLI

Get a Guard key

Create a custom model

Send the first request

If connection fails

Sections

On this page