# grok-cli

> A terminal coding agent for the Grok API, with X search, sub-agents and remote control

- Category: AI Coding / Autonomous Coding Agents
- Language: TypeScript
- Licence: MIT
- Repository: https://github.com/superagent-ai/grok-cli
- Canonical page: https://ai-tldr.dev/tools/grok-cli/

## In short

grok-cli is a terminal coding agent that talks to xAI's Grok API. It is community-built and not affiliated with xAI, and it uses the publicly documented API, so you bring your own Grok API key from x.ai. It sits in the Autonomous Coding Agents category of the AI Coding tools and is open-source, written in TypeScript and licensed MIT.

## Overview

grok-cli is a terminal coding agent that talks to xAI's Grok API. It is community-built and not affiliated with xAI, and it uses the publicly documented API, so you bring your own Grok API key from x.ai. The interactive experience is an OpenTUI interface built on Bun; the project recommends a modern terminal emulator such as WezTerm, Alacritty, Ghostty or Kitty for it.

Beyond the usual edit-and-run loop it leans on what the Grok API offers: real-time X search and web search are first-class tools, sub-agents are enabled by default, and a built-in `computer` sub-agent (backed by agent-desktop, macOS only) can drive the host desktop through accessibility snapshots — the documented loop is snapshot, resolve refs, act, snapshot again, rather than screenshot-and-guess.

It is also built to run unattended. A headless `--prompt` mode exits after one turn and does not need terminal UI support, `--format json` emits a newline-delimited stream of step-level events (`step_start`, `text`, `tool_use`, `step_finish`, `error`) for scripts and CI, and `--batch-api` routes unattended work through xAI's Batch API for cheaper delayed runs. A background daemon supports recurring schedules, sessions can be resumed by id, and pairing it once with Telegram lets you drive the agent from a phone while the CLI keeps running.

## What it does

- Interactive OpenTUI coding agent built with Bun, plus a headless one-shot `--prompt` mode for scripts and CI
- Real-time X search and web search as built-in tools, across the Grok model lineup
- Sub-agents on by default, including a macOS `computer` sub-agent for desktop automation via accessibility snapshots
- Structured output with `--format json` — semantic step events rather than scraped text
- `--batch-api` for lower-cost unattended runs through xAI's Batch API
- Recurring and one-time schedules driven by a background daemon (`grok daemon --background`)
- Resumable sessions (`grok --session latest`) and Telegram pairing for remote control
- Self-management commands: `grok update`, `grok uninstall --keep-config`

## Getting started

You need a Grok API key from x.ai. The install script is the supported path; the Bun global install is an alternative if Bun is already on your PATH.

1. Install

   Install with the project's script, or globally with Bun.

```bash
curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash

# alternative (requires Bun on PATH)
bun add -g grok-dev
```

2. Start it on a project

   Run it interactively in the current directory, or point it at a repository.

```bash
grok
grok -d /path/to/your/repo
```

3. Run it headlessly

   One prompt, then exit — for scripts, CI and scheduled work. Add --format json for a machine-readable event stream, or --batch-api for cheaper unattended runs.

```bash
grok --prompt "run the test suite and summarize failures"
grok --prompt "summarize the repo state" --format json
grok --prompt "review the repo overnight" --batch-api
```

4. Keep work running

   Resume a saved session, list the models and their pricing hints, or start the daemon that recurring schedules need.

```bash
grok --session latest
grok models
grok daemon --background
```

## When to use it

- Reach for it when your provider of choice is Grok and you want a terminal agent that speaks its API directly
- Reach for it when a coding task needs live X or web context rather than the model's training data
- Reach for it to script agent work in CI, where the JSON event stream is easier to consume than TUI output
- Reach for it for scheduled maintenance jobs — a nightly changelog update or an overnight repo review over the Batch API