Grok CLI: AI-Powered Terminal Assistant for Files and Bash Commands

Grok CLI embeds conversational AI directly into your terminal environment. Powered by Grok-3, the tool interprets natural language instructions and translates them into system actions. Whether you need to inspect a file, generate new code, or run shell commands, you can simply describe the task in plain English. Grok identifies the necessary utility and executes the work on your behalf. The entire experience is housed in an interactive terminal UI that supports project-specific custom instructions to refine the AI's behavior.

Natural Language Interface
Interact with your machine through a conversational interface driven by Grok-3. Communicate with your system as easily as you would with a colleague.

Intelligent File Management
Grok automatically determines the best approach to view, create, or modify files. You focus on the content while the AI handles the specific file operations.

Bash Integration
Execute shell commands via conversation. Instead of struggling with obscure flags and syntax, describe the desired outcome and let Grok construct the command for you.

Contextual Tool Selection
The assistant analyzes your request and selects the appropriate tool from its internal suite. This allows you to stay focused on the high-level task rather than the underlying mechanics.

Interactive Terminal UI
Built on the Ink framework, the interface is clean, responsive, and highly readable, transforming the terminal into a more intuitive workspace.

Global Installation
A simple npm i -g @vibe-kit/grok-cli makes the tool available system-wide. Once installed, you can launch the assistant from any directory by typing grok.

Installing Grok CLI

Requirements:

• Node.js version 16 or higher
• A Grok API key obtained from X.AI

Recommended: Global Installation

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

Local Development Setup

1. Clone the repository: git clone <repository>
2. Navigate to the directory: cd grok-cli
3. Install dependencies: npm install
4. Build the project: npm run build
5. Link the package locally: npm link

Configuring Grok CLI

After acquiring your API key from X.AI, you can authenticate using one of the following methods:

Environment Variable
export GROK_API_KEY=your_api_key_here

.env File
Rename .env.example to .env and insert your key into the designated field.

Command Line Flag
Pass the key directly when starting the tool:
grok --api-key your_api_key_here

Using Grok CLI

• Launch the assistant: grok
• Target a specific working directory: grok -d /path/to/project

Custom Instructions

You can tailor Grok’s behavior by placing a .grok/GROK.md file in your project’s root directory. The assistant reads this file upon startup and adjusts its responses to match your project requirements.

Setup Process

1. Create the configuration folder: mkdir .grok
2. Create the instruction file: touch .grok/GROK.md
3. Add your specific preferences to the file.

Example Configuration

# Grok CLI Custom Instructions

- Write all new code in TypeScript.
- Use React functional components with hooks.
- Prefer explicit typing and const assertions over inferred types for better clarity.
- Include JSDoc comments for all public functions and interfaces.
- Maintain consistency with the existing code style and architectural patterns in this project.

Grok loads these rules automatically when operating within that directory. These instructions are appended to the system prompt, ensuring the AI prioritizes your project's standards over its default settings.

Example Prompts

Instead of memorizing commands, simply tell Grok what you need to achieve:

💬 "Show me what's inside package.json"
💬 "Create a file called hello.js that contains a simple console.log"
💬 "Find all TypeScript files located in the src directory"
💬 "Replace oldFunction with newFunction in all JavaScript files"
💬 "Execute the test suite and display the output"
💬 "Show me the current directory structure"

Grok CLI Architecture

• Agent: Manages the logic for processing commands and coordinating execution.
• Tools: The underlying utilities that handle text editing and bash operations.
• UI: Terminal interface components built with Ink for a modern CLI experience.
• Types: Comprehensive TypeScript definitions ensuring system-wide type safety.