🤖 Conversational AI: Natural language interface powered by Grok-3
📝 Smart File Operations: AI automatically uses tools to view, create, and edit files
⚡ Bash Integration: Execute shell commands through natural conversation
🔧 Automatic Tool Selection: AI intelligently chooses the right tools for your requests
🔌 MCP Tools: Extend capabilities with Model Context Protocol servers (Linear, GitHub, etc.)
💬 Interactive UI: Beautiful terminal interface built with Ink
🌍 Global Installation: Install and use anywhere with npm i -g @vibe-kit/grok-cli

Installation

Prerequisites

Node.js 16+
Grok API key from X.AI

Global Installation (Recommended)

npm install -g @vibe-kit/grok-cli

Local Development

git clone <repository>
cd grok-cli
npm install
npm run build
npm link

Setup

Get your Grok API key from X.AI
Set up your API key (choose one method):

Method 1: Environment Variable

export GROK_API_KEY=your_api_key_here

Method 2: .env File

cp .env.example .env
# Edit .env and add your API key

Method 3: Command Line Flag

grok --api-key your_api_key_here

Method 4: User Settings File Create ~/.grok/user-settings.json:

{
  "apiKey": "your_api_key_here"
}

Custom Base URL (Optional)

You can configure a custom Grok API endpoint (choose one method):

Method 1: Environment Variable

export GROK_BASE_URL=https://your-custom-endpoint.com/v1

Method 2: Command Line Flag

grok --api-key your_api_key_here --baseurl https://your-custom-endpoint.com/v1

Method 3: User Settings File Add to ~/.grok/user-settings.json:

{
  "apiKey": "your_api_key_here",
  "baseURL": "https://your-custom-endpoint.com/v1"
}

Usage

Interactive Mode

Start the conversational AI assistant:

grok

Or specify a working directory:

grok -d /path/to/project

Headless Mode

Process a single prompt and exit (useful for scripting and automation):

grok --prompt "show me the package.json file"
grok -p "create a new file called example.js with a hello world function"
grok --prompt "run npm test and show me the results" --directory /path/to/project

This mode is particularly useful for:

CI/CD pipelines: Automate code analysis and file operations
Scripting: Integrate AI assistance into shell scripts
Terminal benchmarks: Perfect for tools like Terminal Bench that need non-interactive execution
Batch processing: Process multiple prompts programmatically

Model Selection

You can specify which AI model to use with the --model parameter or GROK_MODEL environment variable:

Method 1: Command Line Flag

# Use Grok models
grok --model grok-4-latest
grok --model grok-3-latest
grok --model grok-3-fast

# Use other models (with appropriate API endpoint)
grok --model gemini-2.5-pro --base-url https://api-endpoint.com/v1
grok --model claude-sonnet-4-20250514 --base-url https://api-endpoint.com/v1

Method 2: Environment Variable

export GROK_MODEL=grok-4-latest
grok

Method 3: User Settings File Add to ~/.grok/user-settings.json:

{
  "apiKey": "your_api_key_here",
  "model": "grok-4-latest"
}

Priority order: --model flag > GROK_MODEL environment variable > user settings > default (grok-4-latest)

Command Line Options

grok [options]

Options:
  -V, --version          output the version number
  -d, --directory <dir>  set working directory
  -k, --api-key <key>    Grok API key (or set GROK_API_KEY env var)
  -u, --base-url <url>   Grok API base URL (or set GROK_BASE_URL env var)
  -m, --model <model>    AI model to use (e.g., grok-4-latest, grok-3-latest) (or set GROK_MODEL env var)
  -p, --prompt <prompt>  process a single prompt and exit (headless mode)
  -h, --help             display help for command

Custom Instructions

You can provide custom instructions to tailor Grok's behavior to your project by creating a .grok/GROK.md file in your project directory:

mkdir .grok

Create .grok/GROK.md with your custom instructions:

# Custom Instructions for Grok CLI

Always use TypeScript for any new code files.
When creating React components, use functional components with hooks.
Prefer const assertions and explicit typing over inference where it improves clarity.
Always add JSDoc comments for public functions and interfaces.
Follow the existing code style and patterns in this project.

Grok will automatically load and follow these instructions when working in your project directory. The custom instructions are added to Grok's system prompt and take priority over default behavior.

MCP Tools

Grok CLI supports MCP (Model Context Protocol) servers, allowing you to extend the AI assistant with additional tools and capabilities.

Adding MCP Tools

Add a custom MCP server:

# Add an stdio-based MCP server
grok mcp add my-server --transport stdio --command "node" --args server.js

# Add an HTTP-based MCP server
grok mcp add my-server --transport http --url "http://localhost:3000"

# Add with environment variables
grok mcp add my-server --transport stdio --command "python" --args "-m" "my_mcp_server" --env "API_KEY=your_key"

Add from JSON configuration:

grok mcp add-json my-server '{"command": "node", "args": ["server.js"], "env": {"API_KEY": "your_key"}}'

Linear Integration Example

To add Linear MCP tools for project management:

# Add Linear MCP server
grok mcp add linear --transport sse --url "https://mcp.linear.app/sse"

This enables Linear tools like:

Create and manage Linear issues
Search and filter issues
Update issue status and assignees
Access team and project information

Managing MCP Servers

# List all configured servers
grok mcp list

# Test server connection
grok mcp test server-name

# Remove a server
grok mcp remove server-name

Available Transport Types

stdio: Run MCP server as a subprocess (most common)
http: Connect to HTTP-based MCP server
sse: Connect via Server-Sent Events

Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build project
npm run build

# Run linter
npm run lint

# Type check
npm run typecheck

Architecture

Agent: Core command processing and execution logic
Tools: Text editor and bash tool implementations
UI: Ink-based terminal interface components
Types: TypeScript definitions for the entire system

License

MIT