Use your X Premium or SuperGrok subscription in pi.
- Vision for text-only models — automatically describe images with a vision-capable Grok model and cache descriptions locally.
- Grok Imagine — generate JPEGs from the TUI or let Grok call the
image_gentool, with inline previews. - Subscription OAuth — sign in through a browser or device code or reuse an official Grok Build login; tokens refresh automatically.
- Coding-tool compatibility — use Grok models with the Cursor-style tools they were trained to call.
- Usage tracking — check account limits, remaining credits, and reset times from pi.
Requires pi 0.80.0 or newer and an xAI/Grok account with access to the selected model. Model availability varies by account, plan, region, and xAI rollout. The Grok Build executable is not required.
pi-grok-cli is an unofficial community integration. It does not bypass xAI access controls, quotas, or billing.
pi install npm:pi-grok-cli
piCheck pi --version if installation fails. Update an older installation with pi update --self.
Inside pi, run:
/login
Choose Grok CLI, then select one of these methods:
- Browser login (default) — opens xAI authorization and completes a PKCE exchange through a local loopback callback. If xAI shows a one-time code instead of redirecting to pi, paste that code into pi to complete the active PKCE exchange.
- Device code login (headless) — displays a URL and short code for SSH, containers, and other headless environments.
- Use existing Grok Build login — appears when a valid official
~/.grok/auth.jsonentry is available. The file is read-only to this extension.
/model grok-cli/grok-composer-2.5-fast
Composer 2.5 is the recommended starting point for agentic coding. Choose an image-capable model when native image input matters.
/grok-cli-usage
This fetches the current account allowance, usage, remaining credits, and reset time. Weekly usage is shown when xAI returns it.
pi update npm:pi-grok-cli
pi remove npm:pi-grok-clipi already includes an xAI provider for the public API. This extension targets the backend used by Grok Build instead.
pi's built-in xai provider |
pi-grok-cli |
|
|---|---|---|
| Authentication | XAI_API_KEY |
xAI OAuth or an externally supplied OAuth token |
| Endpoint | api.x.ai |
cli-chat-proxy.grok.com |
| Usage accounting | Public API billing | Grok account allowance and credits |
| Best fit | Public API access and API-key billing | Grok Build model access, Composer 2.5, and Cursor-tool compatibility |
The Grok Build and public API catalogs can overlap. Use the provider that matches the account access and billing model you intend to use.
The table describes metadata bundled with this extension, not live model discovery. Context limits are the values registered in pi; xAI may enforce different limits or change availability without notice.
| Model ID | Registered context | Reasoning | Input |
|---|---|---|---|
grok-composer-2.5-fast |
200K | no | text; images can be described through vision routing |
grok-build |
512K | yes | text + image |
grok-4.3 |
1M | yes | text + image |
grok-4.5 |
500K | yes | text + image |
grok-4.20-0309-reasoning |
2M | yes | text + image |
grok-4.20-0309-non-reasoning |
2M | no | text + image |
grok-4.20-multi-agent-0309 |
2M | yes | text + image |
Pi's thinking-level control is forwarded to grok-4.3, grok-4.5, and grok-4.20-multi-agent-0309. Unsupported models have reasoning parameters removed before the request.
The model-cost metadata shown by pi consists of bundled per-token estimates. It is not a conversion of Grok subscription credits. Use /grok-cli-usage for account limits and xAI's pricing documentation for current public API prices.
The catalog is static for the lifetime of the extension process. Use PI_GROK_CLI_MODELS to filter, reorder, or expose a server-supported model ID that has not been bundled yet.
Browser login listens on 127.0.0.1:56122 by default and falls back to an ephemeral port if needed. A pasted callback URL or query string must include the matching OAuth state. In separated browser/runtime setups, xAI may instead display a one-time authorization code; pi accepts it only through the manual input channel and binds its exchange to the active PKCE verifier. Prefer the full state-bearing callback when xAI provides one, and never share either form. Device-code login avoids callback-port forwarding entirely. Pi stores the resulting credentials and refreshes them automatically before expiry.
When the official Grok Build has a verified ~/.grok/auth.json entry for the bundled issuer and client ID, /login offers it as an explicit choice. pi-grok-cli never silently selects, logs, or writes those credentials. Expired credentials use the same refresh implementation as credentials created by this extension; a failed refresh returns to fresh login.
For automation that already has an OAuth access token, GROK_CLI_OAUTH_TOKEN skips interactive login. Direct tokens are not refreshed; replace them before they expire.
Grok models are trained to call Cursor-style tools. pi-grok-cli registers compatible names and argument normalization so those calls work in pi.
| Category | Tools |
|---|---|
| File | Read, Write, StrReplace, Edit, Delete, LS |
| Search | Grep, Glob |
| Terminal | Shell |
| Web | WebSearch when pi-web-access is installed |
| Image generation | image_gen |
The shims activate only while the selected provider is grok-cli. Other providers retain their normal pi tool set.
Install optional web search support with:
pi install npm:pi-web-access@^0.13.0pi-web-access 0.13.0 or newer is required. When grok-cli is active, WebSearch delegates through pi-web-access's public extension entry and replaces pi's native web_search tool. Other providers are unaffected. Restart pi or run /reload after installing it in an existing session.
When pi's read or Read tool returns an image and the active model does not support image input, pi-grok-cli can:
- Send the image to an image-capable Grok model (
grok-buildby default). - Replace the image block with the generated text description.
- Let the active text-only model reason over that description.
Vision routing is enabled by default and handles up to four images per tool result. It is a lossy description step, not native vision. Image-capable active models receive images directly and are never routed through the describer.
Descriptions are persisted by image hash, model, and prompt in ~/.pi/grok-cli-vision-cache.json. A cache hit avoids another describer request, but the active model still processes the description text. The cache stores descriptions, hashes, and metadata—not raw image data.
Run /grok-cli-imagine <prompt> to generate a JPEG directly, or let a Grok model call the image_gen tool. Both paths use the current Grok CLI OAuth token with xAI's Imagine endpoint and save numbered images under the current pi session:
~/.pi/agent/sessions/<encoded-cwd>/<sessionId>/images/1.jpg
The command accepts --aspect (or --aspect-ratio), --out (or -o), and the currently supported --resolution 1k. For example: /grok-cli-imagine --aspect 16:9 a moonlit mountain lake. Ephemeral sessions fall back to the system temporary directory. Inline previews require a terminal image protocol supported by pi and terminal.showImages to be enabled; the saved path remains available otherwise.
Kitty-protocol terminals use internal PNG preview sidecars under images/.previews/; the generated JPEG remains the public output. A request for one image produces one image_gen call, while explicitly requesting multiple images allows parallel calls.
The image_gen tool activates only for the grok-cli provider. Its model-facing result contains paths only, so generated image bytes are not added to subsequent model context.
Use /grok-cli-imagine:scope to toggle image_gen between Grok CLI-only and all-provider availability. The selection persists in ~/.pi/grok-cli-imagine.json and applies immediately.
/grok-cli-usage requests billing data each time it runs; it does not reuse stale quota data. It reports monthly usage and, when available, weekly utilization. Reset times use the system's local timezone.
| Command | Description |
|---|---|
/grok-cli-usage |
Fetch current quota, remaining credits, and reset times. |
/grok-cli-imagine <prompt> |
Generate and preview an image. Supports --aspect, --out, and --resolution 1k. |
/grok-cli-imagine:scope |
Toggle whether image_gen is available only to Grok CLI or to every provider. |
/grok-cli-vision:status |
Show vision state, describer model, configuration path, and cache statistics. |
/grok-cli-vision:on / /grok-cli-vision:off |
Enable or disable vision routing. |
/grok-cli-vision:cache-clear |
Remove all cached image descriptions. |
Vision configuration is read from ~/.pi/grok-cli-vision.json. The file is created after the first setting change and defaults to:
{
"enabled": true,
"model": "grok-build",
"maxImages": 4,
"cacheEnabled": true,
"cacheMaxEntries": 100
}model must identify an image-capable model. Invalid values are reported and replaced with safe defaults. Manual changes apply on the next image read.
| Variable | Default | Description |
|---|---|---|
PI_GROK_CLI_MODELS |
all bundled models | Comma-separated model IDs to expose, in display order. Unknown IDs receive generic text-only metadata. |
GROK_CLI_OAUTH_TOKEN |
— | Use an external access token instead of /login. No automatic refresh. |
| Variable | Default | Description |
|---|---|---|
PI_GROK_CLI_BASE_URL |
https://cli-chat-proxy.grok.com/v1 |
Override the API base URL. |
GROK_CLI_BASE_URL |
— | Fallback when PI_GROK_CLI_BASE_URL is unset. |
PI_GROK_CLI_OAUTH_CLIENT_ID |
bundled client ID | Override the OAuth client ID. |
PI_GROK_CLI_OAUTH_SCOPE |
openid profile email offline_access grok-cli:access api:access |
Override OAuth scopes. |
PI_GROK_CLI_CALLBACK_HOST |
127.0.0.1 |
Browser callback host. |
PI_GROK_CLI_CALLBACK_PORT |
56122 |
Preferred callback port; falls back to an ephemeral port. |
PI_GROK_CLI_TOKEN_TIMEOUT_MS |
30000 |
Timeout for OAuth token requests. |
PI_GROK_CLI_IMAGINE_BASE_URL |
https://api.x.ai/v1 |
Override the Imagine API base URL. |
PI_GROK_CLI_IMAGINE_MODEL |
grok-imagine-image-quality |
Override the Imagine image model. |
Only point the base URL overrides at an endpoint you trust. The configured endpoint receives the OAuth bearer token, prompts, and model context.
| Problem | What to do |
|---|---|
grok-cli is missing from /model |
Confirm the package appears in pi list, run /login, choose Grok CLI, then restart pi or run /reload. |
| Browser login cannot bind or complete | Paste the complete callback URL into pi when prompted. If xAI displays a one-time code instead, paste it into the same prompt. Otherwise, use device-code login or adjust PI_GROK_CLI_CALLBACK_HOST and PI_GROK_CLI_CALLBACK_PORT. Never post the callback URL or authorization code publicly. |
| Authentication returns HTTP 401 or 403 | Run /login again and confirm the account can access the selected model. Replace an expired GROK_CLI_OAUTH_TOKEN if using the bypass. |
| Inference returns HTTP 426 | Update the extension with pi update npm:pi-grok-cli; the Grok Build endpoint enforces client-version headers. |
| A listed model is unavailable | Availability can differ by account or region, and the catalog is bundled rather than discovered live. Try another model or update the extension. |
/grok-cli-usage reports a billing refresh failure |
Retry later. A billing-endpoint failure does not necessarily mean inference is unavailable. |
WebSearch is unavailable |
Install pi-web-access, then restart pi or run /reload. |
| Images are not being described | Run /grok-cli-vision:status, confirm routing is on, and verify Grok authentication. Native image-capable models bypass routing by design. |
Like every pi extension, pi-grok-cli runs with the user's system permissions. Its tool shims can read, write, edit, and delete files or execute shell commands when the active model calls them. Review third-party extension source before installing it.
| Data | Destination or storage |
|---|---|
| OAuth authorization and token exchange | auth.x.ai; credentials are stored by pi in ~/.pi/agent/auth.json by default. |
| Optional official Grok Build credential reuse | Read from the verified entry in ~/.grok/auth.json; pi-grok-cli does not write this file. |
| Prompts, model context, tool definitions, and tool results | cli-chat-proxy.grok.com. |
| Account usage requests | The Grok Build proxy's /billing endpoints. |
| Images handled by vision routing | Sent to the configured Grok describer model through the proxy. |
| Imagine prompts and generated images | Prompts are sent to api.x.ai; decoded JPEGs are saved under the pi session images directory or the requested output path. |
| Vision cache | Local description text and hashes in ~/.pi/grok-cli-vision-cache.json; raw images are not cached. |
| Optional web searches | Delegated to pi-web-access and its configured search provider. |
Environment variables can leak through process inspection, logs, or child processes. Prefer /login over GROK_CLI_OAUTH_TOKEN for normal interactive use.
See SECURITY.md for supported versions, private vulnerability reporting, disclosure expectations, and the complete trust boundaries. Do not include tokens, authorization codes, callback URLs, prompts, or private project data in public issues.
This project is not affiliated with or endorsed by xAI. The Grok Build endpoint, models, headers, and account policies can change without notice.
Report bugs and feature requests through GitHub Issues. Include the pi version, pi-grok-cli version, selected model, login method, and exact error message. Remove tokens and private project data before posting.
For local development:
bun install
pi -e .
bun run checkPull requests should include tests for behavior changes and pass bun run check.
MIT © 2026 kenryu42