grok-cli Documentation

Grok can run shell commands inside a Shuru microVM sandbox to isolate the agent from your host filesystem and network.

Requirements: macOS 14+ on Apple Silicon.

Usage:

• CLI: Use the --sandbox flag.
• TUI: Use the /sandbox command.

Sandbox Configuration Options:

• Network: Off by default. Use --allow-net to enable or --allow-host to restrict.
• Port forwards: Use --port 8080:80.
• Resource limits: Configure CPUs, memory, and disk size via settings or the /sandbox TUI panel.
• Checkpoints: Start from a saved environment snapshot.
• Secrets: Inject API keys into the VM without exposing them to the guest.

Settings are stored in ~/.grok/workspace-trust.json for workspace-specific persistence, ~/.grok/user-settings.json for user-wide settings, and .grok/settings.json for project-specific settings.

To launch the interactive OpenTUI coding agent, simply run:

grok

You can also specify a specific project directory to start the session in:

grok -d /path/to/your/repo

You can control Grok via Telegram by creating a bot and pairing it with the CLI.

1. Create a bot with @BotFather and copy the token.
2. Set the TELEGRAM_BOT_TOKEN environment variable or add telegram.botToken to ~/.grok/user-settings.json.
3. Start grok, open the **/remote-control** flow in the TUI, and select Telegram.
4. In Telegram, send the **/pair** command to your bot and enter the 6-character code provided in your terminal.

Note: The CLI process must remain running for the bot to work (long polling).

For a headless setup without the TUI, use:

grok telegram-bridge

{
  "telegram": {
    "botToken": "YOUR_BOT_TOKEN"
  }
}

You can install grok-cli using a shell script or via bun if you have it installed on your PATH.

Prerequisites:

• A Grok API key from x.ai.
• A modern terminal emulator (e.g., WezTerm, Alacritty, Ghostty, or Kitty) for the interactive OpenTUI experience.
• For macOS desktop automation, ensure your terminal app has Accessibility permissions enabled in System Settings.

You can schedule headless prompts to run on a recurring schedule or once using natural language.

Recurring Schedules: Require the background daemon to be running:

grok daemon --background

To manage schedules in the TUI, use the /schedule command.

Grok can transcribe voice notes and audio files sent via Telegram using the Grok Speech-to-Text API. This requires a valid GROK_API_KEY.

Configure these settings in ~/.grok/user-settings.json:

{
  "telegram": {
    "botToken": "YOUR_BOT_TOKEN",
    "audioInput": {
      "enabled": true,
      "language": "en"
    }
  }
}

You can define custom foreground sub-agents in ~/.grok/user-settings.json. Each agent requires a name, model, and instruction.

Note: You cannot use the names general, explore, vision, verify, or computer as these are reserved for built-in agents.

{
  "subAgents": [
    {
      "name": "security-review",
      "model": "grok-4.3",
      "instruction": "Prioritize security implications and suggest concrete fixes."
    }
  ]
}

Hooks allow you to execute shell commands at specific agent lifecycle events (e.g., PreToolUse, PostToolUse, UserPromptSubmit).

Execution Logic:

• Hook commands receive JSON event details on stdin.
• They can return JSON on stdout.
• Exit codes: 0 = success, 2 = block the action, other = non-blocking error.

Configure hooks in ~/.grok/user-settings.json using a matcher to target specific tools (like bash).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint-before-edit.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

You can provide your Grok API key using one of the following methods:

1. Environment Variable (Recommended for CI): export GROK_API_KEY=your_key_here
2. Project .env file: Add GROK_API_KEY=your_key_here to a .env file in your project root.
3. CLI Flag: Pass it once using grok -k your_key_here.
4. User Settings: Save it permanently in ~/.grok/user-settings.json.

When defining hooks, you can use a matcher string to target specific values for certain events. For example, in PreToolUse events, the matcher string is compared against the tool_name.

• If a hook entry has no matcher defined, it matches every occurrence of that event.
• If a matcher is defined, it will only trigger when the event's specific value (e.g., a tool name) exactly matches the matcher string.

Agent Skills are specialized workflows that the Grok agent can use to improve task consistency. Skills are defined by a directory containing a SKILL.md file with YAML frontmatter.

Skill Structure

Each skill must reside in a directory with a SKILL.md file. The SKILL.md file must include a YAML frontmatter block containing:

• name: The unique identifier for the skill.
• description: A summary of what the skill does.

Skill Discovery Locations

The agent discovers skills in two scopes:

1. User Scope: Located in ~/.agents/skills/<skill_name>/SKILL.md.
2. Project Scope: Located in <project_root>/.agents/skills/<skill_name>/SKILL.md (and searched upwards through parent directories until the Git root is reached).

Note: Project-level skills override user-level skills if they share the same name.