xAI

CLI Workflows

The CLI is best when you want to stay in the shell, script Grok Code, or inspect saved state without opening the TUI.

grok run vs grok exec

Use grok run

Use run when you want one readable answer in the terminal.

Example:

bash
grok run "review the current diff for bugs"

Use grok exec

Use exec when you want script-friendly behavior.

Examples:

bash
grok exec "format the summary as markdown"
cat ci.log | grok exec "explain the failure"
grok exec --json "run tests and summarize failures"

What exec does differently:

  • streams progress to stderr
  • prints the final result to stdout
  • supports --json for JSONL events
  • reads from stdin if prompt text is omitted or stdin is piped

Important Side Effect Difference

Successful CLI run and exec flows apply filesystem edits live.

That is different from the TUI:

  • TUI work usually stages an artifact for review in Gate
  • CLI work applies the resulting edit artifact immediately on success

Use the TUI when you want a governed review step before files change.

Common exec Flags

  • --json: emit JSONL events to stdout
  • --quiet: suppress progress and print only the final result
  • --ephemeral: do not persist the session
  • --sandbox: choose read-only, workspace-write, or full-access
  • --full-auto: auto-approve tool calls with a workspace-write sandbox
  • -o, --output: write the final response to a file

Images

Both run and exec accept -i or --image.

Supported image formats:

  • .png
  • .jpg
  • .jpeg
  • .gif
  • .webp

Inspecting And Managing Saved Work

Useful commands:

bash
grok sessions
grok export abc123
grok replay abc123
grok session rename abc123 "routing cleanup"
grok session delete abc123

Branch-aware commands accept session@branch.

Examples:

bash
grok export session-id@branch-id
grok replay session-id@branch-id --filter tool

If your query matches more than one session or branch, Grok Code stops and asks you to be more specific.

Bootstrap And Compatibility Imports

Initialize a project scaffold:

bash
grok init

What it creates:

  • .grok/config.toml
  • .grok/rules.md
  • GROK.local.md
  • .grok/commands/review.md

Import compatibility files from other tools:

bash
grok import claude
grok import cursor
grok import mcp-json --path .mcp.json

Generate a lightweight AGENTS.md scaffold:

bash
grok deepinit

MCP And Remote MCP

Manage local MCP server definitions:

bash
grok mcp add demo -- echo hi
grok mcp list
grok mcp remove demo

Manage xAI Remote MCP definitions:

bash
grok mcp remote add docs https://docs.x.ai/api/mcp
grok mcp remote list
grok mcp remote remove docs

Use the TUI /mcp inspector when you want health and runtime context, not just config entries.

Harness And Verification

Run harness evidence flows:

bash
grok harness run runtime
grok harness report
grok harness diff runtime <run-id>
grok harness bless baseline runtime --run-id <run-id>

See Governance And Verification for when to use harness vs bench.

Auth, Rate Limits, And Updates

Useful commands:

bash
grok login
grok whoami
grok wait
grok update
grok update --list-backups
grok update --rollback latest

Important behavior:

  • grok login validates the key before saving it
  • grok whoami shows the effective endpoint, model, region, and response storage state
  • grok wait only helps after Grok Code has recorded a live rate-limit event
  • grok update keeps backups for rollback

Teams, Skills, And CI Repair

Useful commands:

bash
grok teams list
grok teams show platform
grok skills
grok ci-fix --log-file ci.log

These are advanced workflows. The TUI is usually easier if you are starting from scratch.

When To Use The TUI Instead

Switch back to the TUI when you need:

  • guided setup or auth repair
  • lane-based review and research
  • staged change governance
  • Recall browsing, bookmarks, and handoffs
  • richer visibility into runtime state

Was this page helpful? Report issues on GitHub.