grok-cli

Agentic AI coding CLI powered by xAI/Grok — orchestration, memory, tools, and autonomous execution.

Install

# From npm (recommended)
npm install -g grok-wr1now
export XAI_API_KEY="your-key-here"
grok "explain this codebase"

# From source
git clone https://github.com/wr1now/grok-cli.git && cd grok-cli && bash setup.sh

Get an xAI API key at https://console.x.ai

Quick Start

Prerequisites: Node.js 20+, git

git clone https://github.com/wr1now/grok-cli.git
cd grok-cli
bash setup.sh

The setup script installs dependencies, builds, runs tests, and tells you next steps.

export XAI_API_KEY="your-key-here"  # get a key at https://console.x.ai

# Interactive REPL (recommended)
./grok -i

# Direct execution
./grok "explain this codebase"

# Full pipeline (preflight → oversight → execution)
./grok run "build a REST API"

# Autonomous mode
./grok run "refactor the auth module" --mode autonomous

# Universal flagship mode
./grok pilot-pro "ship this repo to launch readiness"

Global Install (optional)

npm link
grok "your goal here"
grok -i
grok run "goal" --mode autonomous

Execution Modes

| Mode | Flag | Preflight | Oversight | Tools | Interaction | |---|---|---|---|---|---| | Normal | --mode normal | interactive (scoped) | auto-scoped | approval required | interactive | | Fast | --mode fast | skip | skip | safe auto-approved | minimal | | Plan | --mode plan | preflight only | skip | no execution (structural) | review only | | Autonomous | --mode autonomous | auto-answer (scoped) | auto-scoped | non-destructive auto | result only |

Scope rules. For short, conversational, or trivial prompts (≤ 12 words without a heavy action verb or file/code reference), preflight and oversight auto-skip the heavy LLM analysis phases and route directly to execution. This prevents grok run "say pong" --mode auto from spending 200+ seconds on competitive analysis and strategy synthesis. Longer prompts with build/ refactor/design verbs still run the full three-phase pipeline.

Commands

# Execution
grok "goal"                         # Direct execution
grok run "goal"                     # Preflight → Oversight → Execute
grok ask "question"                 # Quick answer, no tools
grok architect "goal"               # Two-phase reasoning pipeline
grok autopilot "goal"               # Agree on plan, execute uninterrupted
grok pilot-pro "goal"               # Universal flagship mode with internal triage

# AI-Powered
grok explain <file>[:<lines>]       # AI code explanation
grok refactor <file>                # AI refactoring suggestions
grok diff                           # AI diff summary + commit suggestion
grok commit                         # AI-generated commit message
grok pr                             # AI-generated PR description

# Project
grok init                           # Create .grok/ directory
grok config                         # View/edit project config
grok dashboard                      # Architecture + progress overview
grok scan                           # Project structure analysis
grok workspace                      # Multi-project workspace

# Development
grok test                           # Run tests
grok lint                           # Typecheck
grok deps                           # Dependency analysis
grok git                            # Git summary
grok security                       # Secret/env scanning
grok search "query"                 # Full-text code search
grok todo                           # Find TODOs in codebase
grok benchmark [N]                  # Provider latency benchmark

# Operations
grok health                         # Provider + system health
grok stats                          # Telemetry dashboard
grok doctor                         # Comprehensive diagnostic
grok eval                           # Execution metrics analysis
grok history                        # Execution timeline
grok export <target>                # Export data (report/decisions/memory/config)
grok clean                          # Remove stale .grok/ data
grok env                            # Full environment info
grok migrate                        # Version migration check
grok plugin                         # Plugin management
grok trajectory                     # Competitor analysis
grok autoresearch start             # Karpathy optimization loop
grok daemon start                   # Background file watcher
grok schedule list                  # Manage scheduled jobs
grok auto-implement                 # Read Obsidian + CLAUDE.md and schedule only executable autonomous work
grok version                        # Version info

# Interactive
grok -i                             # REPL with session presets, slash commands, streaming
grok --resume-session-id <id> "goal" # Resume a persisted batch/stream session
grok --help                         # Show all commands and flags

Developer Docs

# Generate the markdown API reference from the package export surface
npm run docs:api

• Markdown output: docs/API_REFERENCE.md
• Source of truth entrypoint: src/index.ts

Architecture

User Goal
    │
    ▼
┌──────────────────────────────────────┐
│  PREFLIGHT (scoped)                  │
│  Clarify → Strategy enrichment only  │
│  when the task actually needs it     │
└──────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────┐
│  OVERSIGHT (scoped)                  │
│  Coherence → Blind Spots → Reframe   │
│  Verdict: proceed / adjust / abort   │
└──────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────┐
│  EXECUTION                           │
│  Route → Plan → Tool Loop → Evaluate│
└──────────────────────────────────────┘
    │
    ▼
  Memory + Decision Log + Telemetry

Built-in Tools

| Tool | Tier | Description | |---|---|---| | echo_text | safe_read | Echo text back | | read_file | safe_read | Read file contents (byte-limited) | | write_file | safe_write | Write or append to file | | edit_file | safe_write | Search-and-replace editing | | list_directory | safe_read | List directory contents | | run_command | shell | Shell command execution | | git_status | safe_read | Git status | | git_diff | safe_read | Git diff | | git_log | safe_read | Git log | | git_commit | safe_write | Stage and commit | | git_checkout | safe_write | Branch switching | | repo_map | safe_read | Project structure map | | grep_search | safe_read | Regex content search | | glob_find | safe_read | File pattern matching | | web_fetch | network | HTTP client (SSRF-protected) | | http_request | network | Full HTTP requests (SSRF-protected) | | web_search | network | Web search | | env_inspector | safe_read | Environment variables (secrets redacted) | | test_runner | shell | Run test suites | | lint_check | shell | Run linters |

See grok health for the full list of registered tools.

.grok/ Directory

.grok/
├── config/          # project.json, providers.json
├── sessions/        # Session state
├── conversations/   # Multi-turn history
├── memory/          # Scoped records (session/project/semantic)
├── policies/        # Policy bundles
├── decision-logs/   # Audit trail
├── oversight/       # Preflight + oversight results
└── tools/           # Project tool definitions (.json)

Project-scoped durability is automatic when projectRoot is available:

• Memory uses the built-in SQLite-backed store when supported, with JSON fallback otherwise
• Decision logs persist to .grok/decision-logs/
• grok history, grok eval, and grok export read persisted artifacts directly and do not require API auth
• --resume-session-id restores both session metadata and persisted conversation context
• REPL /save, normal exit, and Ctrl+C suspension all persist session state and conversation history

Environment Variables

| Variable | Description | |---|---| | XAI_API_KEY | xAI/Grok API key (primary) | | XAI_OAUTH_BEARER | OAuth bearer (alternative) | | XAI_MODEL | Override default model (e.g. grok-3-mini) | | ANTHROPIC_API_KEY | Anthropic adapter (optional) | | OPENAI_API_KEY | OpenAI adapter (optional) |

Development

npm run build       # Compile TypeScript
npm run typecheck   # Type check only
npm run test        # Build + run all tests
npm run clean       # Remove dist/

Experimental Features

These are functional but still under the 2.0 release gate. Use with caution.

• grok pilot-pro "goal" — universal flagship mode with internal triage. Short or conversational prompts route to a fast grounded path, local coding goals route to project-aware execution, and broad product goals enter the deep loop (intelligence → strategy → build → validate).
• grok mcp start — Expose tools via MCP server
• Pilot Pro preset in REPL (/preset pilot-pro)
• grok architect "goal" — Two-phase reasoning pipeline for design/refactoring tasks. Refuses short/conversational prompts; use grok or grok run --mode fast instead.

Security

• All tool execution goes through an approval gate with configurable risk tiers
• Destructive operations always require explicit user approval
• Network tools block localhost, RFC 1918, link-local, and cloud metadata endpoints (SSRF protection)
• Environment inspector redacts secrets by default
• Dangerous execution modes require typing "yes" to confirm

Legal & Privacy

grok-cli is a locally-running CLI tool. By default it collects no data and sends nothing to the publisher. Prompts go directly from your machine to the LLM provider API using your own API key.

| Document | Description | |----------|-------------| | Terms of Service | License grant, acceptable use, warranty disclaimer, limitation of liability | | Privacy Policy | What is collected (nothing by default), optional Sentry telemetry, local SQLite memory, GDPR & CCPA rights | | GDPR/CCPA Compliance Checklist | GDPR 8/10, CCPA 5/5 — open gaps documented |

All legal documents are templates pending review by qualified counsel before public launch.

License

MIT