grok-agent-kit

English docs | 简体中文文档

Community-built, unofficial CLI + MCP + skills toolkit for xAI Grok.

Requirements

• Node.js 22+
• an XAI_API_KEY

Install

npm install -g grok-agent-kit
grok-agent-kit doctor
grok-agent-kit chat --prompt "Hello from Grok"

Or run it without a global install:

npx -y grok-agent-kit chat --prompt "Hello from Grok"
npx -y grok-agent-kit auth status
npx -y grok-agent-kit auth validate-management
npx -y grok-agent-kit doctor
npx -y grok-agent-kit chat --prompt "Stream a quick summary" --stream
npx -y grok-agent-kit chat --prompt-file ./context.txt
npx -y grok-agent-kit chat --prompt "Analyze these logs:" < ./logs.txt
npx -y grok-agent-kit chat --interactive
npx -y grok-agent-kit x-search --interactive
npx -y grok-agent-kit web-search --interactive
npx -y grok-agent-kit chat --session notes --prompt "Start a persistent CLI session"
npx -y grok-agent-kit chat --session notes --prompt "Continue that session"
npx -y grok-agent-kit sessions show notes
npx -y grok-agent-kit sessions export notes --format markdown --output ./notes.md
npx -y grok-agent-kit x-search --prompt "Latest xAI posts" --stream
npx -y grok-agent-kit web-search --prompt "Latest xAI docs" --stream
npx -y grok-agent-kit x-search --session notes --prompt "Latest xAI posts"
npx -y grok-agent-kit web-search --session notes --prompt "Latest xAI docs"
npx -y grok-agent-kit sessions list
npx -y grok-agent-kit x-search --prompt "Latest xAI posts"
npx -y grok-agent-kit web-search --prompt "Latest xAI docs"
npx -y grok-agent-kit mcp

Environment

XAI_API_KEY=your_key_here
XAI_BASE_URL=https://api.x.ai/v1
XAI_MANAGEMENT_API_KEY=your_management_key_here
XAI_MANAGEMENT_BASE_URL=https://management-api.x.ai
GROK_AGENT_KIT_MODEL=grok-4
GROK_AGENT_KIT_TIMEOUT_MS=30000
GROK_AGENT_KIT_RETRY_MAX_ATTEMPTS=3
GROK_AGENT_KIT_RETRY_BASE_DELAY_MS=250
GROK_AGENT_KIT_RETRY_MAX_DELAY_MS=4000

The CLI retries transient rate-limit, timeout, and 5xx failures by default so long-running MCP agent sessions are less likely to fail on a single flaky request. The published npm package officially supports Node.js 22+, and the GitHub Actions CI / publish workflows use Node.js 22 to match that baseline. The GitHub Actions publish workflow also upgrades npm to 11.5.1+ because npm Trusted Publishing currently requires npm 11.5.1 or newer.

Doctor

• doctor checks local environment and state-path basics before you start using chat, search, or MCP
• current checks include Node.js version, XAI_API_KEY, XAI_BASE_URL, XAI_MANAGEMENT_API_KEY, XAI_MANAGEMENT_BASE_URL, GROK_AGENT_KIT_MODEL, live xAI API connectivity, live management API connectivity when configured, and local sessions.json readability
• use grok-agent-kit doctor --bundle ./doctor-bundle.json to save a redacted diagnostic bundle for issue reports or remote debugging

Client setup generator

Use the built-in generator when you want a ready-to-paste config or install command for a supported client:

npx -y grok-agent-kit clients codex --mode published
npx -y grok-agent-kit clients claude-code --mode published
npx -y grok-agent-kit clients gemini-cli --mode published
npx -y grok-agent-kit clients openclaw --mode local --project-path /absolute/path/to/grok-agent-kit

For local development mode, point --project-path at your clone root so the generated snippet references apps/cli/dist/bin.js.

Local sessions

• chat --session <name> continues a named local session
• chat --reset-session --session <name> resets that session before sending the new prompt
• interactive chat, x-search, and web-search print a one-line startup hint and support /help for reprinting the available slash commands
• chat --stream writes response text incrementally as it arrives
• x-search --stream and web-search --stream stream search text as it arrives
• x-search --session <name> and web-search --session <name> reuse the same local session continuity
• chat --previous-response-id <id> continues from a raw xAI response id
• sessions show <name> prints the saved local transcript for a session, including models and token totals when available
• sessions list shows saved sessions
• sessions delete <name> removes a saved session record
• sessions export <name> --format markdown|json exports a saved session to stdout
• sessions export <name> --format markdown|json --output <path> writes the export directly to a file

Piping and files

• chat --prompt-file <path>, x-search --prompt-file <path>, and web-search --prompt-file <path> load UTF-8 prompt text from a file
• chat --system-file <path> loads a reusable long-form system prompt from a file
• piped stdin is appended after --prompt / --prompt-file with a blank line separator
• stdin-only usage works when you omit --prompt and pipe the entire prompt content in

Supported surfaces

• CLI for direct usage
• MCP over grok-agent-kit mcp
• search guidance for Codex, Claude Code, OpenClaw, and Gemini CLI

More docs

• Repository README
• Codex setup
• Claude Code setup
• Gemini CLI setup
• OpenClaw setup
• Grouped client guides