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.02.01 (npm package 1.2.1). 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).

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.

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

# Single prompt
grok -p "Explain this repository in one paragraph"

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

# 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
-p, --prompt <prompt>       Process a single prompt and exit
--max-tool-rounds <rounds>  Maximum tool execution rounds

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.

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.

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
GROK_MAX_TOKENS	Response output cap sent to xAI	1536
GROK_MAX_TOOLS	Maximum tool declarations sent in one request	200

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.
• Tool-argument parsing fails with explicit diagnostics instead of generic JSON parser errors.
• grok mcp test shuts down stdio transports after tests.

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;
• synthetic xAI streaming function-call argument assembly;
• 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://github.com/sponsors/lcv-leo

License

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