yrzhe/claude-skills/grok-cli

grok-cli

Use this skill when the user or an agent needs a local CLI wrapper around Grok/xAI with:

• Browser-based xAI / SuperGrok OAuth login using Authorization Code + PKCE.
• Optional XAI_API_KEY fallback.
• xAI /v1/responses chat calls.
• Grok Imagine image generation (sync) and video generation (async poll).
• X/Twitter search through xAI's server-side x_search Responses tool.
• Persistent local session history in SQLite.
• Multi-session switching, export, and summarization.

Safety and credential rules

Never ask the user to paste their xAI password. Use grok-cli login to open the xAI authorization URL in a browser. Do not scrape browser cookies, automate grok.com, or capture interactive login credentials. OAuth tokens are stored locally under ~/.grok-cli/auth.json with owner-only file permissions when supported by the OS.

Prefer OAuth for SuperGrok users. API keys are supported only as fallback through XAI_API_KEY or grok-cli key set.

Do not print access tokens, refresh tokens, API keys, or ID tokens. grok-cli status sanitizes credential output.

Image and video generation are paid xAI operations (≈ $0.02 / image, ≈ $0.40 / 8s video — video is ~20x an image). The CLI refuses paid generation in non-interactive mode unless --yes is passed; never auto-pass --yes for an agent without the user's intent. No credentials are bundled in this package — each user logs in with their own SuperGrok / X Premium account via grok-cli login.

Installation

From the skill folder:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Smoke test without network:

grok-cli --help
grok-cli status

Login

Local machine with browser:

grok-cli login

Remote SSH/container session:

# On your local machine, in a separate terminal:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host
 
# On the remote host:
grok-cli login --no-browser
# Open the printed URL locally.

Alternative API key fallback:

export XAI_API_KEY="..."
# or store locally:
grok-cli key set

Main commands

# Single-turn chat, saved to current/default session
grok-cli ask "What is the meaning of life?"
 
# Interactive chat
grok-cli chat -s research
 
# Image generation (Grok Imagine, sync) — paid, needs --yes
grok-cli image "a neon cyberpunk fox, sticker art" --yes -o fox.jpg -n 2
 
# Video generation (Grok Imagine, async poll) — paid ~20x an image, needs --yes
grok-cli video "a paper plane gliding over a city at sunset" --yes -o plane.mp4
grok-cli video --fetch <request_id> --json     # check an existing job
 
# X Search via Grok server-side x_search
grok-cli search "What are people on X saying about the latest xAI algorithm update?" --save
 
# Limit search to handles
grok-cli search "Grok image feature reactions" --allowed xai elonmusk --from 2026-05-01
 
# Enable image/video understanding for matching posts
grok-cli search "Show visual reactions to Grok features" --images --videos
 
# Sessions
grok-cli session new ai-market --use
grok-cli session list
grok-cli session use thesis
grok-cli session export ai-market -o ai-market.md
 
# Summarize long session for future compact context
grok-cli summarize -s ai-market

Agent invocation contract

For Codex or another agent, call the CLI rather than importing internals unless you need a custom integration.

Preferred machine-readable calls:

grok-cli ask "<prompt>" --session "<session>" --json
 
grok-cli search "<query>" --allowed xai --from 2026-05-01 --json --save
 
grok-cli status

JSON responses include the response id, model, answer, citations, inline citations, status, and usage where available.

Data layout

Default local state:

~/.grok-cli/
  auth.json          # OAuth/API-key credential state, sanitized by status output
  config.json        # base_url, default_model, search_model, current_session
  sessions.sqlite3   # sessions, messages, citations, summaries

Set GROK_CLI_HOME=/path/to/state to isolate state for tests or a specific agent workspace.

Implementation notes for agents

• grok-cli login uses the xAI OIDC discovery document and Authorization Code + PKCE.
• OAuth defaults are based on the public Hermes Agent implementation for xai-oauth.
• X Search is implemented by sending tools: [{"type":"x_search"}] to /v1/responses, matching Hermes' documented behavior.
• xAI's public Responses API documents /v1/responses, response ids, retrieval, deletion, and server-side response storage. This skill defaults to store:false for data-sovereignty reasons.
• If x_search returns a provider/model error, switch search_model to grok-4.20-reasoning or another model with x_search entitlement.

Troubleshooting

• No xAI credentials available: run grok-cli login, set XAI_API_KEY, or use grok-cli key set.
• Login callback cannot connect on a remote host: forward local port 56121 to the remote host before opening the URL.
• state_mismatch: rerun login; do not reuse old authorization URLs.
• invalid_grant or refresh failure: run grok-cli login again.
• x_search not enabled for this model/account: verify that your SuperGrok account has access and try grok-cli config set search_model grok-4.20-reasoning.

Source basis

This package is based on public behavior documented by Hermes Agent and xAI docs, not on private credentials or browser-cookie scraping. See docs/sources.md for references.