Grok Build

https://github.com/xai-org/grok-build
Admin
Grok Build is a terminal-based AI coding agent and TUI that understands codebases, executes...
Tokens:279,760
Snippets:2,067
Trust Score:8.2
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Quick Start Commands

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Commands to install Grok and run it in interactive, headless, and agent modes. Use these to get started quickly.

```bash
# Install
curl -fsSL https://x.ai/cli/install.sh | bash

# Interactive TUI
grok

# Headless (for scripts/automation)
grok -p "Explain this codebase"

# Agent mode (for IDE/app integration)
grok agent stdio
```

--------------------------------

### TUI usage examples with grok

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Shows common ways to start the TUI: specifying a project directory, sending an initial prompt, adding project-specific rules, and enabling auto-approve mode.

```bash
# Start in a specific project
grok --cwd ~/projects/my-app

# Start with an initial task
grok --prompt "Review this codebase and suggest improvements"

# Add project-specific rules
grok --rules "Always use TypeScript. Prefer functional components."

# Auto-approve mode for trusted tasks
grok --always-approve --prompt "Format all files"
```

--------------------------------

### Browse docs with /docs

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/04-slash-commands.md

Use /docs to browse the built-in How-to Guides, open the online Build docs, or jump to a guide by title. Bare /docs opens the How-to Guides picker, /docs web opens https://docs.x.ai/build/overview, and /docs <title> opens a specific guide by case-insensitive title match.

```text
/docs
/docs web
/docs Getting Started
```

--------------------------------

### Install released binary with curl or PowerShell

Source: https://github.com/xai-org/grok-build/blob/main/README.md

Use these commands to install the prebuilt binary on macOS, Linux, or Windows (Git Bash or PowerShell). The first command installs on macOS/Linux/Git Bash, the second on Windows PowerShell, and the third verifies the installation.

```sh
curl -fsSL https://x.ai/cli/install.sh | bash   # macOS / Linux / Git Bash
irm https://x.ai/cli/install.ps1 | iex          # Windows PowerShell
grok --version
```

--------------------------------

### Verify installation with grok --version

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md

Verifies the Grok Build installation by printing the installed version.

```bash
grok --version
```

--------------------------------

### plain output example

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/14-headless-mode.md

Example of the default plain text output format, suitable for direct display or piping.

```text
Here's a summary of the codebase...
```

--------------------------------

### Open onboarding tutorial with /tutorial

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/04-slash-commands.md

Use /tutorial to open the onboarding tutorial, a short list of topics each about a 30-second read. Nothing auto-shows; this command or the command palette is the way in.

```text
/tutorial
```

--------------------------------

### SessionStart hook configuration

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/custom-hooks.md

Example hook configuration file that runs a command when a Grok session starts. Place it at ~/.grok/hooks/session-start.json. The hook runs automatically on SessionStart after starting or restarting a session.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
         { "type": "command", "command": "echo \"🚀 Grok session started in $(pwd)\"" }
        ]
      }
    ]
  }
}
```

--------------------------------

### Slash Commands for Quick Actions

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md

Slash commands are typed in the prompt to perform quick actions. The example shows commands to switch the model, compress conversation history, toggle always-approve mode, and start a new session.

```plaintext
/model grok-4.6                 # Switch model
/compact                          # Compress conversation history
/always-approve                   # Toggle always-approve mode
/new                              # Start a new session
```

--------------------------------

### Filesystem MCP server example

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Runs the filesystem server via npx, allowing access to the specified directory.

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
```

--------------------------------

### Get the session ID from a previous JSON response

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/14-headless-mode.md

Use this command to start a session and capture its ID from the JSON output. The --output-format json flag ensures the response includes the sessionId field, which can be extracted with jq.

```bash
grok -p "Remember: the secret number is 42" --output-format json
```

--------------------------------

### Install xai-crash-handler and check previous crash

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-crash-handler/README.md

Initialize the crash handler: call check_previous_crash() before install() because install() truncates last-crash.bin. Install before spawning threads or async runtime since sigaltstack is per-thread. install() creates crash_dir if missing.

```rust
use std::path::PathBuf;

let crash_dir = PathBuf::from("/home/user/.myapp/crash");

// check_previous_crash MUST be called before install(), because
// install() opens last-crash.bin with O_TRUNC.
if let Some(r) = xai_crash_handler::check_previous_crash(&crash_dir) {
    eprintln!("Crashed last session: {}", r.signal_name);
    eprintln!("Report: {}", r.report_path.display());
}

// install() before any threads or async runtime — sigaltstack is per-thread.
// Creates crash_dir if it does not exist.
xai_crash_handler::install(xai_crash_handler::CrashHandlerConfig {
    app_version: env!("CARGO_PKG_VERSION").to_string(),
    crash_dir,
});
```

--------------------------------

### Postgres MCP server example

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Runs the Postgres server via npx, connecting to the specified database URL.

```toml
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]
```

--------------------------------

### Install specific version with curl

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md

Installs a specific version of Grok Build (0.1.42) using the bash installer.

```bash
curl -fsSL https://x.ai/cli/install.sh | bash -s 0.1.42
```

--------------------------------

### Custom MCP server example

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Runs a custom server executable with arguments and custom timeouts.

```toml
[mcp_servers.my-tools]
command = "/usr/local/bin/my-mcp-server"
args = ["--config", "/etc/my-mcp.json"]
startup_timeout_sec = 30
tool_timeout_sec = 120
```

--------------------------------

### GitHub MCP server example

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Runs the GitHub server via npx, requiring a GitHub personal access token in the environment.

```toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxxxxxxxxxxx" }
```

--------------------------------

### Install specific version with PowerShell

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md

Installs a specific version of Grok Build (0.1.42) on Windows using the PowerShell installer.

```powershell
$env:GROK_VERSION="0.1.42"; irm https://x.ai/cli/install.ps1 | iex
```

--------------------------------

### Install latest stable release with PowerShell

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md

Installs the latest stable release of Grok Build on Windows using the native PowerShell installer.

```powershell
irm https://x.ai/cli/install.ps1 | iex
```

--------------------------------

### Add marketplace and install plugin

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/09-plugins.md

Adds a marketplace and installs a plugin with trust. The marketplace can be specified as GitHub shorthand, a git URL, or a local path.

```bash
grok plugin marketplace add my-org/my-org-plugins   # GitHub shorthand, a git URL, or a local path
grok plugin install gdrive --trust
```

--------------------------------

### Build & Test Instructions

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/12-project-rules.md

Provides build and test commands, including prerequisites like Docker for integration tests.

```markdown
# Build & Test

- Run `npm test` before committing
- Use `npm run lint` to check code style
- Build with `npm run build` -- ensure no TypeScript errors
- Integration tests: `npm run test:e2e` (requires Docker)

```

--------------------------------

### Install Grok CLI (latest and specific version)

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Install the latest stable version with curl, or specify a version by appending the version number to the install script command.

```bash
# Install latest stable
curl -fsSL https://x.ai/cli/install.sh | bash

# Install a specific version
curl -fsSL https://x.ai/cli/install.sh | bash -s 0.1.42
```

--------------------------------

### Install plugin with trust

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/09-plugins.md

Installs a plugin with trust, granting it permission to load skills, commands, hooks, MCP servers, and LSP servers. Use this when installing plugins from sources you trust.

```bash
grok plugin install <source> --trust
```

--------------------------------

### Write marketplace.json index

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/09-plugins.md

Example `marketplace.json` index file that names the marketplace and lists each plugin. The `source` field can be a local path or a separate repository URL with a pinned `sha`.

```json
{
  "name": "My Org Plugins",
  "description": "Internal skills and tools",
  "owner": { "name": "Platform Team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "gdrive",
      "description": "Search and edit Google Drive, Docs, Sheets, and Slides",
      "category": "productivity",
      "source": { "type": "local", "path": "./plugins/gdrive" }
    }
  ]
}
```

--------------------------------

### Launch the TUI with grok [OPTIONS]

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md

Starts the interactive TUI. Use command-line flags to configure the working directory, initial prompt, rules, approval mode, sandbox, theme, and more.

```bash
grok [OPTIONS]
```

--------------------------------

### Start Grok with default authentication

Source: https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md

Launch Grok. On first launch, it opens the browser to authenticate with grok.com; credentials are stored in ~/.grok/auth.json and refreshed automatically.

```bash
grok
```
Tokens:
Raw