grok-cli

LCV-maintained Grok CLI runtime with hardened xAI Responses API streaming and Model Context Protocol support.

Install. npm install -g @lcv-ideas-software/grok-cli (npmjs.com) or npm install -g @lcv-ideas-software/grok-cli --registry=https://npm.pkg.github.com (GitHub Packages mirror).

Status. Maintained. Current release: v01.06.03 (npm package 1.6.3). See CHANGELOG.md for the release history. Public tags follow the organization display-tag standard (v00.00.00) while npm packages keep SemVer (1.x.y).

The version history at a glance:

| Release | Scope | |---|---| | v01.06.03 | Site sponsor card iteration. site/index.html GitHub Sponsors iframe (caixa branca cross-origin) substituído por link card dark navy com ❤ pink + meta cyan + seta animada; card movido para DEPOIS dos botões (lcv.dev/sponsor primário, GitHub Sponsors alternativa). Companion ship Phase 3 (12 repos). | | v01.06.02 | Patch — site/index.html visual identity refresh. GitHub Pages sponsor page reskin to the new LCV org dark-first navy/cyan visual identity (palette #050b18/#38bdf8/#34d399, radial gradients, glow shadows, gradient text on h1). Coordinated companion ship with cross-review-v1 1.12.9, cross-review-v2 v2.18.7, deepseek-cli 0.3.1, sponsor-motor APP v01.02.02, and .github-org/site (org root + /sponsor). No change to the published npm tarball (files[] does not include site/); only the GitHub Pages page changes. Patch bump (no public surface change). | | v01.06.01 | CodeQL security hardening. Enabled JavaScript/TypeScript CodeQL coverage, removed clear-text API-key-id logging, eliminated TOCTOU file-read patterns, documented intentional user-approved remote data boundaries for xAI, batch payloads and Morph Fast Apply, and patched the fast-uri advisory in the lockfile. | | v01.06.00 | Integrated agent upgrade surface. Added model catalog/reasoning policy, --format headless output, durable sessions, read-only plan mode, verify evidence manifests, xAI Batch API helpers, explicit schedules, media batch payload preparation, and disabled-by-default remote/desktop/sandbox boundaries. | | v01.05.01 | Dependabot automerge parity. Aligned the Dependabot automerge workflow with cross-review-v1 and cross-review-v2: pull_request_target, Dependabot-only execution, and GitHub native auto-merge after required checks pass. Also preserves the sponsor redirect to https://www.lcv.dev/sponsor?project=grok-cli. | | v01.05.00 | Safe auth/status surface. Added grok status, startup runtime status, xAI API-key metadata via /v1/api-key, redacted user/team/key identifiers, and an explicit grok login boundary that refuses unsupported Grok.com/X credential, cookie, or private-token emulation. Subscription-plan login remains pending an official xAI CLI-safe authorization grant. | | v01.04.00 | Peer-review-mode emits plain assistant text (was: ndjson {role:user,content} + {role:assistant,content} wrap). Consumer orchestrators such as cross-review-v1 parse a <cross_review_status> block at the tail of stdout; the JSON wrap put "} after the closing tag and defeated the tail check (Step 2 health probe of cross-review-v1 v1.8.4 on 2026-05-05 reproduced peer_status=null + protocol_violation=true on healthy READY votes). v1.4.0 writes only the last assistant content to stdout under --peer-review-mode; non-peer-review headless mode preserves the legacy ndjson per-message output for OpenAI-compatible tooling. Error path under peer-review-mode goes to stderr. | | v01.03.00 | Safe peer-review mode for cross-review orchestration. Added --prompt-stdin, --peer-review-mode, built-in tool disabling for controlled peer use, per-run MCP config and allowlist controls, default grok-4.3, and smoke coverage for the safe peer path. | | v01.02.01 | Dependabot and publishing hardening. Restored the dependency baseline after semver-major Dependabot updates failed CI, ignored semver-major updates, required the Install, check and smoke gate before automerge, and aligned repository metadata for Trusted Publishing parity. | | v01.02.00 | LCV package identity and MCP transport baseline. Adopted @lcv-ideas-software/grok-cli, moved repository metadata to the org, hardened .grok/settings.json loading, switched to official MCP SDK transports including Streamable HTTP, fixed streaming function-call/tool-output handling, and added CI, npm publishing, Pages, Dependabot, Sponsors, and governance files. |

What It Does

grok-cli is an interactive and headless command-line agent for xAI Grok models. It uses the xAI Responses API for model calls and exposes a developer-oriented tool surface:

• File viewing and editing.
• Shell command execution with confirmation.
• Ripgrep-backed search.
• Todo planning.
• Native web_search and x_search tool declarations.
• MCP tools loaded from .grok/settings.json.
• Model catalog and reasoning policy for supported Grok models.
• Durable local sessions, read-only planning, verification manifests, Batch API helpers, explicit schedules, and media batch payload preparation.

The built-in default model is grok-4.3, aligned with xAI's current Responses API examples. Override it per run with --model or GROK_MODEL.

This repository is the LCV-maintained runtime line. It was initialized from an npm-installed Grok CLI maintenance runtime, then hardened around the current xAI Responses API and MCP transport behavior observed in production use.

Install

npm install -g @lcv-ideas-software/grok-cli

PowerShell:

[Environment]::SetEnvironmentVariable("GROK_API_KEY", "<GROK_API_KEY>", "User")

Restart the terminal after changing Windows environment variables.

Usage

# Interactive mode
grok

# Version, configured auth, visible account metadata, and plan boundary
grok status

# Supported auth methods and explicit subscription-login boundary
grok login

# Model catalog and reasoning policy
grok models
grok status --model grok-4.20-multi-agent

# Single prompt
grok -p "Explain this repository in one paragraph"
grok -p "Summarize this repo" --format jsonl
grok -p "Continue from prior work" --session latest

# Use a specific working directory
grok --directory C:/Users/leona/lcv-workspace

# Read-only plan mode
grok plan "Upgrade the CLI output contract"

# Local verification evidence
grok verify

# xAI Batch API helpers
grok batch create "nightly-review"
grok batch add <batch-id> --prompt "Review this repository" --model grok-4.3

# Explicit local schedules; no daemon is started automatically
grok schedule add weekly-review --prompt "Run the weekly review"
grok schedule run weekly-review --dry-run

# Media request preparation for official xAI API batch payloads
grok media prepare image "Product screenshot in terminal style"

# MCP inventory
grok mcp list

# MCP connection test
grok mcp test openaiDeveloperDocs

Common options:

-d, --directory <dir>       Set working directory
-k, --api-key <key>         Grok API key
-u, --base-url <url>        Grok API base URL
-m, --model <model>         Model to use
--reasoning-effort <effort> Reasoning effort: auto, none, low, medium, high, xhigh
-p, --prompt <prompt>       Process a single prompt and exit
--prompt-stdin              Read a headless prompt from stdin
--format <format>           Headless format: ndjson, text, json, jsonl
--session <id>              Durable session id, latest, or new
--peer-review-mode          Safe headless peer-review mode
--disable-mcp               Do not load MCP servers for this run
--mcp-config <path>         Load MCP servers from this JSON config
--allowed-mcp-server-names  Allow one MCP server name (repeatable)
--max-tool-rounds <rounds>  Maximum tool execution rounds

Authentication and Plan Status

Current supported runtime authentication is the documented xAI API-key flow:

• GROK_API_KEY environment variable.
• --api-key for a single run.
• apiKey in ~/.grok/user-settings.json.

grok status validates the configured API key against xAI's documented GET /v1/api-key endpoint and displays only redacted metadata: key name/state, truncated user/team/key IDs, ACLs, model, and base URL.

grok login is intentionally conservative. The CLI does not collect Grok.com/X credentials, reuse browser cookies, or call private Grok.com app endpoints. Grok.com/X subscription-plan usage will be added only if xAI exposes an official CLI-safe authorization grant for that purpose.

Models and Reasoning

grok models prints the local model catalog used by the CLI. The catalog is not a substitute for xAI's live billing/model pages; it is the runtime policy source for safe request construction.

Reasoning policy is intentionally conservative:

• grok-4.3 supports explicit reasoning when the user sets --reasoning-effort or GROK_REASONING_EFFORT; accepted efforts are none, low, medium, and high.
• grok-4.20-multi-agent receives explicit reasoning by default because that model is used for multi-agent deliberation workflows; accepted efforts are low, medium, high, and xhigh.
• grok-4-latest is treated as automatic reasoning and the CLI does not attach explicit reasoning config.

This keeps the user-selected model in control while avoiding unsupported request fields.

xAI Responses API

The runtime calls POST /v1/responses and follows the continuation model expected by the Responses API:

• previous_response_id is retained between turns.
• Tool outputs are sent back as function_call_output.
• Parallel tool calls are completed as a batch before continuation.
• Streaming function-call arguments are accumulated until complete before a tool is executed.

This avoids the failure mode where response.output_item.added arrives before arguments are complete and the runtime attempts JSON.parse(""), surfacing as Unexpected end of JSON input.

Headless Output

Headless prompts support:

• --format ndjson (default legacy OpenAI-compatible message lines).
• --format text (final assistant text only).
• --format json (single structured result).
• --format jsonl (semantic event stream: assistant_message, tool_call, and tool_result).

--peer-review-mode always overrides output formatting and emits the final assistant text only. This is required so cross-review-v1 and cross-review-v2 can parse the structured status block at the tail of stdout.

Sessions, Planning, Verification, Batch and Schedules

Durable sessions are stored under ~/.grok/sessions unless GROK_SESSION_DIR is set. Use --session new, --session latest, or a specific session id. The CLI stores prompts, messages and final text, but never stores API keys.

grok plan is a read-only local planner. It inspects repository metadata and prints likely touchpoints and constraints without editing files or running mutating commands.

grok verify runs local evidence commands and writes a manifest under ~/.grok/verify unless --no-write is used.

grok batch wraps the official xAI Batch API. grok media prepare emits batch request payloads for official xAI media models. grok schedule stores explicit local schedules in ~/.grok/schedules.json; it never installs or starts a daemon automatically.

Remote Data Boundary

Interactive prompts, explicit @file references and grok batch payloads are sent to the configured xAI-compatible API endpoint when the user asks the CLI to run a model request. The CLI does not send files implicitly; file contents are included only when referenced by the prompt or by a user-provided batch payload. grok status redacts API-key metadata and never logs the API key value.

Morph Fast Apply is a separate remote apply-model integration. It sends the selected file content to Morph API only after user confirmation, and it asks for confirmation of the returned diff before writing the response back to disk.

MCP

Project MCP servers are read from:

.grok/settings.json

Supported transport forms:

• stdio
• http / Streamable HTTP
• sse legacy endpoints, with /mcp URLs routed through Streamable HTTP

The loader preserves server names from object keys, merges top-level env and headers into transport config, and expands ${VAR} placeholders from the process environment.

Headless integrations can override MCP loading for a single run:

grok --peer-review-mode --prompt-stdin `
  --mcp-config C:/path/reviewer-minimal.mcp.json `
  --allowed-mcp-server-names memory `
  --allowed-mcp-server-names ultrathink

--peer-review-mode also disables built-in file editing, shell, todo, web, and X tools so a supervising orchestrator can provide a controlled MCP-only review surface.

Example:

{
  "mcpServers": {
    "openaiDeveloperDocs": {
      "transport": {
        "type": "sse",
        "url": "https://developers.openai.com/mcp"
      }
    }
  }
}

Configuration

| Variable | Description | Default | | --- | --- | --- | | GROK_API_KEY | xAI API key | required | | GROK_BASE_URL | API base URL | https://api.x.ai/v1 | | GROK_MODEL | CLI-selected model override | project/user setting, then grok-4.3 | | GROK_MAX_TOKENS | Response output cap sent to xAI | 1536 | | GROK_MAX_TOOLS | Maximum tool declarations sent in one request | 200 | | GROK_REASONING_EFFORT | Reasoning effort for supported models | model policy | | GROK_SESSION_DIR | Durable session directory | ~/.grok/sessions | | GROK_VERIFY_DIR | Verification evidence directory | ~/.grok/verify | | GROK_SCHEDULES_FILE | Explicit schedule store | ~/.grok/schedules.json | | GROK_MCP_CONFIG | Per-run MCP config path override | unset | | GROK_ALLOWED_MCP_SERVER_NAMES | Comma-separated MCP allowlist | all configured | | GROK_DISABLE_MCP | Disable MCP loading when truthy | unset | | GROK_DISABLE_BUILTIN_TOOLS | Disable built-in file/bash/search/todo tools when truthy | unset | | GROK_PEER_REVIEW_MODE | Safe cross-review peer mode when truthy | unset |

User settings are stored under ~/.grok/user-settings.json. Project settings are read from .grok/settings.json; reading project settings no longer creates the file as a side effect.

Security

Threat model: single-user trusted workstation. The CLI can read and edit files, execute shell commands after confirmation, and pass configured MCP tool calls through to external servers.

Hardening in this LCV line:

• Official MCP SDK transports for stdio, SSE and Streamable HTTP.
• Secret-like values redacted from top-level error output.
• Atomic JSON writes for local settings.
• Durable sessions and verification artifacts are stored under ~/.grok with restrictive file permissions where the platform supports them.
• Tool-argument parsing fails with explicit diagnostics instead of generic JSON parser errors.
• grok mcp test shuts down stdio transports after tests.
• Remote control, desktop automation, external sandboxes, and subscription-login emulation stay disabled unless an explicit future release adds a reviewed, official, opt-in implementation.

Do not commit .grok/, .env, API keys, local session files, or node_modules/.

Development

This initial repository is dist-first because it was bootstrapped from an installed npm runtime package. Source recovery/refactoring to TypeScript can happen in a later release, but the current committed runtime is dist/.

npm ci
npm test
node dist/index.js --version

npm test runs:

• syntax checks over all dist/**/*.js;
• smoke checks for package metadata/version alignment;
• model catalog and reasoning policy;
• headless JSONL output formatting;
• durable session persistence;
• read-only plan mode;
• verify dry-run manifests;
• Batch API payload construction;
• media request payload preparation;
• synthetic xAI streaming function-call argument assembly;
• xAI API-key metadata normalization for the status surface;
• parallel tool-output continuation;
• Todo input normalization;
• MCP config loader invariants.

Release Automation

The repository follows the same automation baseline as cross-review-v1 and cross-review-v2:

• Pushes to main run CI.
• Pushes to main auto-create a padded display tag such as v01.02.00 from package.json.
• The tag dispatches publish.yml.
• publish.yml publishes to npmjs.com with npm Trusted Publishing / OIDC provenance, without NPM_TOKEN.
• The same workflow mirrors the package to GitHub Packages.
• Pages deploy from site/ to https://grok-cli.lcv.dev/.
• Dependabot watches npm and GitHub Actions daily.

Links

• Repository: https://github.com/LCV-Ideas-Software/grok-cli
• Package: https://www.npmjs.com/package/@lcv-ideas-software/grok-cli
• Site: https://grok-cli.lcv.dev/
• Organization: https://www.lcv.dev/
• Sponsors: https://www.lcv.dev/sponsor

License

Apache-2.0. See LICENSE, NOTICE, and THIRDPARTY.md.