Grok CLI

https://github.com/superagent-ai/grok-cli
Admin
A conversational AI CLI tool powered by Grok with intelligent text editor capabilities, tool usage,...
Tokens:55,820
Snippets:715
Trust Score:9.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Build Project

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Install project dependencies and build the project from a clone. This is the initial setup for development.

```bash
bun install
bun run build
bun run start
```

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

### Project Instructions Example

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Provide custom instructions for your project in `AGENTS.md`. This Markdown file guides the agent's behavior and understanding of the project.

```markdown
# Project Instructions

This is a TypeScript React frontend project.
Key patterns:
- Use React Hooks for state management
- All components in src/components
- Tests in src/__tests__

Do not modify build configuration without approval.
```

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

### Install Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Install the grok-cli using either the provided install script or the bun package manager.

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

```bash
bun add -g grok-dev
```

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

### Install Bun and Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Installs the Bun runtime and the Grok CLI globally. This is an alternative if the bundled Bun in the install script is not preferred.

```bash
curl -fsSL https://bun.sh/install | bash
bun add -g grok-dev
```

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

### Configuration Precedence Example

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Demonstrates the order in which Grok CLI checks for model configuration settings, starting from environment variables down to default values.

```bash
# 1. Check environment
export GROK_MODEL=grok-4.3

# 2. Check .env file
# GROK_MODEL=grok-4.20-non-reasoning

# 3. Check .grok/settings.json
# { "model": "grok-4.20-0309-reasoning" }

# 4. Check ~/.grok/user-settings.json
# { "model": "grok-4-fast" }

# 5. Use default
# "grok-4.3"

# Final effective model: grok-4.3 (from environment)
```

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

### Start and Manage a Background Server Process

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Shows how to start a server process in the background, retrieve its logs, and stop it when no longer needed.

```typescript
// Start server in background
const bg = bash.startBackground("npm run dev");
const serverId = bg.backgroundProcess.id;

// Wait for it to start
await bash.execute("sleep 2");

// Check if it's running
const logs = bash.getProcessLogs(serverId, 10);
console.log(logs.output);

// Stop when done
await bash.stopProcess(serverId);
```

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

### Install Dependencies

Source: https://github.com/superagent-ai/grok-cli/blob/main/AGENTS.md

Installs project dependencies, including Husky for pre-commit hooks. Biome runs on staged files.

```bash
bun install
```

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

### Install agent-desktop Post-installation Script

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Runs the post-installation script for agent-desktop if Bun blocks the native binary download.

```bash
node ./node_modules/agent-desktop/scripts/postinstall.js
```

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

### Install grok-cli globally with Bun

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Install grok-cli as a global package using Bun. This method requires Bun to be installed and available on your system's PATH.

```bash
bun add -g grok-dev
```

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

### User Settings File Example

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Example structure for the user settings file located at ~/.grok/user-settings.json. This file can configure API keys, models, and other agent behaviors.

```json
{
  "apiKey": "xai-...",
  "model": "grok-4.3",
  "baseUrl": "https://api.x.ai/v1",
  "reasoningEffort": "medium",
  "sandboxMode": "shuru",
  "telegram": { ... },
  "subAgents": [ ... ],
  "mcpServers": [ ... ],
  "hooks": { ... },
  "lsp": { ... },
  "payment": { ... }
}
```

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

### Example: Delegate Exploration Task

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Example of delegating an exploration task to the 'explore' agent to find project dependencies and their licenses.

```typescript
// Delegate exploration
await agent.task({
  agent: "explore",
  description: "Library dependencies",
  prompt: "Find all npm packages, versions, and their licenses in the project"
});
```

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

### Example: Generate and Send Image to Telegram

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/telegram.md

This is an example command demonstrating how to generate an image and then send it to Telegram using the grok-cli.

```bash
grok "Generate an image of a sunset, then send it to Telegram"
```

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

### JSON: User Settings Example

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/agent.md

An example of the user settings JSON file, showing configuration for API key, model, sandbox mode, and Telegram bot token.

```json
{
  "apiKey": "xai-...",
  "model": "grok-4.3",
  "sandboxMode": "shuru",
  "telegram": {
    "botToken": "..."
  }
}
```

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

### Generate New Image Example

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Example of generating a new image with specified prompt, aspect ratio, and resolution.

```typescript
// Generate a new image
await agent.generate_image({
  prompt: "A serene mountain landscape at sunset, oil painting style",
  aspect_ratio: "16:9",
  resolution: "2k"
});
```

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

### Install Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Installs the Grok CLI using a curl script. This is the primary method for setting up the command-line interface.

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

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

### Start a Background Process

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Start a command to run in the background. The method returns immediately with process information.

```typescript
const result = bash.startBackground("npm start");
const processId = result.backgroundProcess?.id;
// Later...
await bash.getProcessLogs(processId, 50);
await bash.stopProcess(processId);
```

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

### Verify curl Installation

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Check if the `curl` command-line tool is installed on your system. This is a prerequisite for running the installation script on macOS.

```bash
# Verify curl is installed
which curl
```

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

### Start Grok CLI with Options

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Launches the grok-cli with specified options and an optional initial message. Use this to customize the agent's behavior, such as setting the project directory, model, or API key.

```bash
grok [OPTIONS] [INITIAL_MESSAGE]
```

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

```bash
grok --model grok-4.20-non-reasoning
```

```bash
grok --session latest
```

```bash
grok -k xai-your-key-here
```

```bash
grok "Fix the bug in src/main.ts"
```

```bash
grok -d /path/to/repo -m grok-4.3 --max-tool-rounds 50
```

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

### computer_click Example

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Demonstrates how to click a desktop element using either its accessibility reference or fallback screen coordinates. Prefer using accessibility refs for reliability.

```typescript
// Click using accessibility ref (preferred)
await agent.computer_click({ ref: "@e5" });

// Click using coordinates (fallback)
await agent.computer_click({ x: 512, y: 384 });
```

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

### startBackground

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Starts a shell command as a background process. This method returns immediately, allowing the command to run independently.

```APIDOC
## startBackground(command: string): ToolResult

Start a command as a background process.

### Parameters
- `command` (string): Bash command to execute in the background.

### Returns
- `{ success: true; backgroundProcess: { id, pid, command } }`

### Note
Returns immediately; the process runs in the background.

### Example
```typescript
const result = bash.startBackground("npm start");
const processId = result.backgroundProcess?.id;
// Later...
await bash.getProcessLogs(processId, 50);
await bash.stopProcess(processId);
```
```

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

### Example: Delegate Code Review Task

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Example of delegating a code quality review task to the 'general' agent. The prompt specifies the directory and review criteria.

```typescript
// Delegate a code review
await agent.task({
  agent: "general",
  description: "Code quality review",
  prompt: "Review the changes in src/components for performance, readability, and potential bugs"
});
```

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

### Edit Existing Image Example

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Example of editing an existing image by providing a prompt and the source image path.

```typescript
// Edit an existing image
await agent.generate_image({
  prompt: "Make the sky more dramatic with stormy clouds",
  source: "assets/landscape.jpg"
});
```

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

### Start Grok Daemon in Background

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Starts the Grok daemon in the background, required for recurring schedules.

```bash
grok daemon --background
```

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

### Start Headless Telegram Bridge

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/telegram.md

Starts the Telegram bridge in headless mode. Ensure the GROK_API_KEY environment variable is set. The bridge runs in the foreground and outputs logs to the console.

```bash
export GROK_API_KEY=xai-...
grok telegram-bridge
```

```text
Telegram bridge started. Check Telegram bot for pairing code.
Long-polling active...
```

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

### computer_snapshot Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for capturing a semantic accessibility snapshot of the desktop UI. Use this to get a structured representation of the UI for further interaction.

```typescript
{
  app?: string;           // Optional app name to scope
  window_id?: string;     // Optional window ID
  interactive_only?: boolean; // Include only interactive elements (default: true)
  include_bounds?: boolean;   // Include element bounds
  compact?: boolean;          // Collapse single-child nodes
  max_depth?: number;         // Max tree depth
  surface?: string;       // "window", "focused", "menu", "menubar", "sheet", "popover", "alert"
}
```

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

### Install Grok CLI with Bash on macOS

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

If you are using an outdated shell on macOS, explicitly use `bash` to execute the Grok CLI installation script. This ensures compatibility.

```bash
# If using an outdated shell, try with bash explicitly
bash -c "$(curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh)"
```

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

### Usage Example for Sub-Agent

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Invoke a custom sub-agent using the Grok CLI by specifying the task name with the --task flag.

```bash
grok --prompt "..." --task security-review
```

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

### Grok Sandbox Configuration with Network Access

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Example JSON configuration for sandbox isolation using Shuru, specifying network access and allowed hosts. This enhances security by limiting resource access.

```json
{
  "sandboxMode": "shuru",
  "sandboxSettings": {
    "allowNet": true,
    "allowedHosts": ["github.com"],
    "cpus": 4,
    "memory": 4096
  }
}
```

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

### Navigate Directories and Get Current Working Directory

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Demonstrates changing the working directory within a project and retrieving the current path using BashTool.

```typescript
const bash = new BashTool("/home/user/project");

// Navigate within project
await bash.execute("cd src/components");
await bash.execute("ls");  // Lists files in src/components

const cwd = bash.getCwd();  // "/home/user/project/src/components"

// Absolute path
await bash.execute("cd /tmp");
console.log(bash.getCwd()); // "/tmp"
```

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

### Check Grok CLI Version

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Retrieve the currently installed version of the Grok CLI. This is useful for reporting issues or verifying updates.

```bash
grok --version
```

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

### BashTool Working Directory Management

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Demonstrates how to get the current working directory and change it using the BashTool's execute method. Note that 'cd' commands directly update the instance's state and do not spawn a new shell.

```typescript
// Initial state
console.log(bash.getCwd()); // "/home/user/project"

// Change directory
await bash.execute("cd src");
console.log(bash.getCwd()); // "/home/user/project/src"

// Relative path resolution
await bash.execute("cd components");
console.log(bash.getCwd()); // "/home/user/project/src/components"

// Go back
await bash.execute("cd ..");
console.log(bash.getCwd()); // "/home/user/project/src"
```

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

### Custom Hook Timeout Configuration

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

Example JSON configuration for setting a custom timeout for a 'PostToolUse' hook. The timeout is specified in seconds.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "./slow-integration-test.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}
```

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

### BackgroundProcessInfo Interface for Running Processes

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/types.md

Provides information about a currently running background process, including its unique ID, process ID (PID), and the command used to start it.

```typescript
interface BackgroundProcessInfo {
  id: number;
  pid: number;
  command: string;
}
```

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

### Create Interactive Telegram Bridge

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/telegram.md

Creates an interactive Telegram bridge instance. Requires bot token, user approval logic, and agent configuration. Call `start()` to begin listening for messages.

```typescript
import { createTelegramBridge, createTurnCoordinator } from "./telegram";
import { Agent } from "./agent/agent";

const bridge = createTelegramBridge({
  token: botToken,
  getApprovedUserIds: () => [123456789],
  coordinator: createTurnCoordinator(),
  getTelegramAgent: (userId) => new Agent(apiKey, baseURL, "grok-4.3", 30),
  onUserMessage: (event) => console.log(`User ${event.userId}: ${event.content}`),
  onAssistantMessage: (event) => console.log(`Assistant: ${event.content}`),
});

bridge.start();
// Later...
await bridge.stop();
```

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

### Grok Hooks Configuration for PreToolUse Event

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Example JSON configuration for defining hooks, specifically a 'PreToolUse' hook that executes a linting script before any tool usage, particularly for bash commands.

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

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

### computer_launch Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for launching an application on the desktop. Specify the application by name or bundle ID, with an optional launch timeout.

```typescript
{
  app: string;            // App name or bundle ID
  timeout_ms?: number;    // Launch timeout in ms (default: varies)
}
```

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

### Run Project from Source with Bun

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Run the project directly from the source code using Bun for development.

```bash
bun run dev      # run from source (Bun)
```

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

### Run Built Project

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Execute the built project using Node.js.

```bash
# or: node dist/index.js
```

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

### File Structure

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/INDEX.md

Overview of the project's directory structure, including master documents and API reference modules.

```bash
ls /output/
├── README.md                      # Master overview and quick reference
├── INDEX.md                       # This file
├── types.md                       # Complete type definitions
├── models.md                      # Model catalog and functions
├── configuration.md               # Configuration reference
├── api-reference/
│   ├── agent.md                   # Agent class documentation
│   ├── tools.md                   # Complete tools reference
│   ├── bash-tool.md               # BashTool class
│   ├── cli.md                     # CLI reference
│   ├── storage.md                 # Storage and session persistence
│   ├── telegram.md                # Telegram integration
│   └── hooks.md                   # Hooks and lifecycle events
```

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

### Run Hook Manually with Sample JSON

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

Demonstrates how to manually execute a hook script using bash, piping sample JSON input to the script. The hook script is expected to be located in ~/.grok/hooks/.

```bash
echo '{"hook_event_name":"PreToolUse","tool_name":"bash","tool_input":{"command":"ls"},"cwd":"/home/user"}' \
  | ~/.grok/hooks/my-hook.sh
```

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

### Configure API Key via Command Line Argument

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Provide the API key directly using the -k flag. This is convenient for local use but not recommended for automated scripts.

```bash
grok -k your_key_here
```

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

### Generate Documentation with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Use the `-p` (or `--prompt`) and `--format json` flags to generate documentation in JSON format.

```bash
grok -p "Generate comprehensive README.md and API documentation" --format json
```

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

### Get Agent Model ID

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/agent.md

Retrieve the identifier for the language model currently used by the agent.

```typescript
getModel(): string
```

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

### Get All Model IDs

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/models.md

Obtain a list of all canonical model identifiers recognized by the system, ordered by priority.

```typescript
export function getModelIds(): string[]
```

```typescript
getModelIds();
// Returns: ["grok-4.3", "grok-4.20-multi-agent-0309", "grok-4.20-0309-reasoning", ...]
```

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

### Execute a Simple Bash Command

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Demonstrates the basic usage of executing a simple bash command like 'ls -la' and logging its output.

```typescript
const bash = new BashTool();

const result = await bash.execute("ls -la");
console.log(result.output);
```

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

### Get Tool Description

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Obtain a markdown-formatted description of the BashTool's capabilities, intended for use by agents.

```typescript
bash.getToolDescription();
```

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

### Headless Mode with Prompt and Directory

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Combines a prompt with a specified directory for headless execution.

```bash
grok -p "show me package.json" --directory /path/to/project
```

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

### Update grok-cli

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Run this command to update your grok-cli installation to the latest version. This command is available for script-installed versions.

```bash
grok update
```

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

### Generate Documentation with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Generate documentation for your project using the Grok CLI and output the results in JSONL format.

```bash
grok -p "Generate a comprehensive README.md for this project" --format json > docs.jsonl
```

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

### Check Grok CLI Version and Help

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Displays the current version of the Grok CLI or shows the help information. Use -v for version and -h for help.

```bash
grok --version
grok -v
```

```bash
grok --help
grok -h
```

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

### Get Agent Session ID

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/agent.md

Retrieve the current session identifier. Returns null if session persistence is not enabled.

```typescript
getSessionId(): string | null
```

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

### computer_list_windows Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for listing visible windows on the desktop. Can optionally filter by application name.

```typescript
{
  app?: string;           // Optional app filter
}
```

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

### Get Next Message Sequence

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/storage.md

Retrieves the next available message sequence number for a given session ID.

```typescript
export async function getNextMessageSequence(
  sessionId: string
): Promise<number>
```

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

### Set Default Model

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Specify the default AI model to be used by the Grok CLI. This example sets the model to 'grok-4.3'.

```json
{
  "model": "grok-4.3"
}
```

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

### Verify Application with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Use the `--verify` flag to have the agent inspect, build, and run your application within a sandbox, generating a verification report. The `-d` flag specifies the application path.

```bash
grok --verify
```

```bash
grok -d /path/to/your/app --verify
```

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

### Get Model Info

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/models.md

Retrieve detailed metadata for a specific model ID or alias. Returns undefined if the model is not found.

```typescript
export function getModelInfo(modelId: string): ModelInfo | undefined
```

```typescript
const info = getModelInfo("grok-4.3");
// Returns:
// {
//   id: "grok-4.3",
//   name: "Grok 4.3",
//   contextWindow: 1000000,
//   inputPrice: 1.25,
//   outputPrice: 2.5,
//   reasoning: true,
//   description: "Recommended flagship reasoning model",
//   ...
// }
```

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

### Analyze Repository with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Use the `--prompt` flag to ask Grok to summarize the structure and purpose of a codebase.

```bash
grok --prompt "Summarize the structure and purpose of this codebase"
```

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

### VerifyRecipe Type Definition

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/types.md

Defines a recipe for application verification. This includes various commands for initialization, bootstrapping, installation, building, and testing.

```typescript
interface VerifyRecipe {
  ecosystem: string;
  appKind: string;
  appLabel: string;
  shellInitCommands: string[];
  bootstrapCommands: string[];
  installCommands: string[];
  buildCommands: string[];
  testCommands: string[];
  startCommand?: string;
  startPort?: string;
  smokeKind: "http" | "cli" | "none";
  smokeTarget?: string;
  evidence: string[];
  notes: string[];
}
```

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

### Display CLI Help

Source: https://github.com/superagent-ai/grok-cli/blob/main/AGENTS.md

Shows the help message for the Grok CLI, listing available commands and options.

```bash
node dist/index.js --help
```

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

### List Available Grok Models

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Run this command to view all models supported by Grok. Use this to ensure you are specifying a valid model name in your commands.

```bash
grok models
```

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

### Use Computer Sub-agent to Launch App and Identify UI Elements

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Uses the computer sub-agent to launch Google Chrome, capture its UI, and identify specific elements like the address bar.

```bash
grok "Use the computer sub-agent to launch Google Chrome, snapshot the UI, and tell me which refs correspond to the address bar and tabs."
```

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

### Retrieve session metadata

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/storage.md

Use the `get` method to fetch session metadata by its ID. Returns the session information or null if not found.

```typescript
async get(sessionId: string): Promise<SessionInfo | null>
```

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

### Create Agent Tools

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Initializes the agent toolkit with necessary dependencies. The `mode` parameter determines the set of available tools.

```typescript
export function createTools(
  bash: BashTool,
  provider: XaiProvider,
  mode: AgentMode = "agent",
  options?: CreateToolsOptions
): ToolSet
```

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

### Get Background Process Logs

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Retrieve recent output from a background process using its ID. Defaults to the last 50 lines.

```typescript
const logs = bash.getProcessLogs(42, 100);
console.log(logs.output); // Last 100 lines of output
```

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

### Create Schedule via Natural Language

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Creates a new schedule by describing it in natural language. This command allows for flexible scheduling of tasks.

```bash
grok "Create a schedule named daily-tests that runs at 9am every weekday and executes npm test"
```

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

### Headless Mode for Repository Review

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Initiates a headless run to review the repository's state.

```bash
grok --prompt "review the repo overnight" --batch-api
```

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

### Configure Sandbox Settings

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Define detailed sandbox settings including network access, allowed hosts, port forwarding, resource allocation (CPUs, memory, disk size), secret injection, base image, guest working directory, host workspace synchronization, and initial shell commands.

```json
{
  "sandboxSettings": {
    "allowNet": false,
    "allowedHosts": ["github.com", "npm.org"],
    "ports": ["8080:3000", "9000:9000"],
    "cpus": 4,
    "memory": 4096,
    "diskSize": 50000,
    "secrets": [
      {
        "name": "GITHUB_TOKEN",
        "fromEnv": "GITHUB_TOKEN",
        "hosts": ["github.com"]
      }
    ],
    "from": "ubuntu:22.04",
    "guestWorkdir": "/app",
    "syncHostWorkspace": true,
    "shellInit": ["apt-get update", "apt-get install -y build-essential"]
  }
}
```

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

### Project Development Utilities

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Execute utility commands for development, including type checking and linting.

```bash
bun run typecheck
bun run lint
```

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

### Get Session Total Tokens - TypeScript

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/storage.md

Retrieves the cumulative token usage for a given session ID. This function is useful for summarizing a session's consumption.

```typescript
export async function getSessionTotalTokens(
  sessionId: string
): Promise<number>
```

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

### SessionStart Hook

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

Fired when a new session is created or an existing one is resumed. Useful for initializing resources or setting up the environment for a session.

```APIDOC
## SessionStart

### Description
Fired when a session is created or resumed.

### Input:
```typescript
interface SessionStartHookInput {
  hook_event_name: "SessionStart";
  source: "startup" | "resume" | "clear";  // How session started
  session_id?: string;
  cwd: string;
}
```
```

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

### Get Supported Reasoning Efforts

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/models.md

Retrieve the list of supported reasoning effort levels for a specific model. Returns an empty array if the model does not support the reasoning_effort parameter.

```typescript
export function getSupportedReasoningEfforts(modelId: string): ReasoningEffort[]
```

```typescript
getSupportedReasoningEfforts("grok-3-mini");     // ["low", "high"]
getSupportedReasoningEfforts("grok-4.3");        // []
```

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

### Initialize and Process Message with Grok Agent

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Demonstrates initializing the Agent class and processing a user message, streaming content chunks until completion. Includes agent cleanup.

```typescript
const agent = new Agent(apiKey, baseURL, "grok-4.3", 30);
for await (const chunk of agent.processMessage("fix this bug")) {
  if (chunk.type === "content") console.log(chunk.content);
  if (chunk.type === "done") break;
}
await agent.cleanup();
```

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

### Get Current Working Directory

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Retrieve the current working directory of the BashTool instance. This reflects any changes made by 'cd' commands executed via the execute() method.

```typescript
bash.getCwd();
```

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

### Explore Dependencies with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Use the Grok CLI to list project dependencies, including their versions and licenses, by specifying the latest session.

```bash
grok --prompt "List all npm dependencies, versions, and licenses" \
  --session latest
```

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

### Specify Project Directory

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Launches Grok CLI and directs it to a specific project directory for analysis or operations.

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

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

### SessionStore.create

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/storage.md

Creates a new session in the database. It takes workspace information and initial session configuration, returning the complete session information.

```APIDOC
## SessionStore.create

### Description
Create a new session in the database.

### Method
`create`

### Parameters
- `workspace` (WorkspaceInfo): Workspace identity (path, git root, etc.)
- `sessionInit` (SessionInit): Initial session configuration
  - `title` (string) - Optional
  - `model` (string) - Required
  - `mode` (AgentMode) - Required

### Returns
Complete SessionInfo with timestamps and ID

### Example
```typescript
const store = new SessionStore();
const session = await store.create(
  {
    id: "workspace-123",
    canonicalPath: "/home/user/my-project",
    displayName: "my-project",
    scopeKey: "...",
    gitRoot: "/home/user/my-project",
    lastSeenAt: new Date(),
  },
  {
    title: "Fix authentication bug",
    model: "grok-4.3",
    mode: "agent",
  }
);
```
```

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

### Add Debug Output to Hook Script

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

Example of adding debug output to a hook script using bash. Standard error (>&2) is used for debug messages and piping the input JSON.

```bash
echo "Debug: received event" >&2
jq . <<< "$1" >&2
```

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

### Configure Hooks in user-settings.json

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

Defines which shell commands to run at specific lifecycle events. Use 'PreToolUse' and 'PostToolUse' to specify commands for tool execution phases. The 'matcher' can be a tool name or '*' for any tool.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint-before-edit.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "logger 'Grok action completed'"
          }
        ]
      }
    ]
  }
}
```

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

### Code Review with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Utilize the `--prompt` flag to request a review of specific code components for performance, security, and accessibility.

```bash
grok --prompt "Review src/components for performance, security, and accessibility issues"
```

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

### BashTool Constructor

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Initializes a new BashTool instance. You can specify an initial working directory and options like sandbox mode.

```APIDOC
## BashTool Constructor

Initializes a new BashTool instance.

### Parameters
- `initialCwd` (string, optional): Initial working directory (default: `process.cwd()`)
- `options` (BashToolOptions, optional): Configuration for sandbox mode and settings.
  ```typescript
  interface BashToolOptions {
    sandboxMode?: "off" | "shuru";
    sandboxSettings?: SandboxSettings;
  }
  ```

### Example
```typescript
import { BashTool } from "./tools/bash";

const bash = new BashTool("/home/user/project", {
  sandboxMode: "shuru",
  sandboxSettings: { allowNet: true }
});
```
```

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

### Start Telegram Bridge in Headless Mode

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Initiate the Telegram bridge for remote control without opening the TUI. This allows Grok to receive commands and process messages via Telegram in a headless environment.

```bash
grok telegram-bridge
```

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

### computer_launch

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Launches a specified application on macOS. Supports setting a timeout for the launch process.

```APIDOC
## computer_launch

### Description
Launch an application.

### Parameters
#### Request Body
- **app** (string) - Required - App name or bundle ID
- **timeout_ms** (number) - Optional - Launch timeout in ms (default: varies)
```

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

### Lint Before Editing Files (Bash Hook)

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

This bash script lints and fixes code using 'npm run lint --fix' before the 'edit_file' tool is executed. It requires Node.js and npm to be installed. The hook is configured to run only for the 'edit_file' tool and has a timeout of 30 seconds.

```bash
#!/bin/bash
# ~/.grok/hooks/lint-before-edit.sh

CWD=$(jq -r '.cwd' <<< "$1")
TOOL=$(jq -r '.tool_name' <<< "$1")

if [[ "$TOOL" == "edit_file" ]]; then
  cd "$CWD"
  npm run lint --fix
  exit $?
fi

exit 0
```

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "~/.grok/hooks/lint-before-edit.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

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

### computer_get Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for reading a specific property from a desktop element. Requires the element's reference and the desired property name.

```typescript
{
  ref: string;            // Element ref
  property?: "text" | "value" | "title" | "bounds" | "role" | "states";
}
```

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

### Loading Configuration Utilities

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Shows the import statements for various utility functions used to load different types of configuration settings in Grok CLI.

```typescript
import {
  getApiKey,
  getBaseURL,
  getCurrentModel,
  loadUserSettings,
  loadPaymentSettings,
  loadValidSubAgents,
  loadMcpServers,
  getCurrentSandboxMode,
  getCurrentSandboxSettings,
} from "./utils/settings";
```

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

### Headless CI Integration with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Integrate the Grok CLI into a headless CI environment to run tests and capture results in JSONL format. Includes a check for the exit code.

```bash
#!/bin/bash
export GROK_API_KEY=...
grok --prompt "Run tests and report results" \
  --format json \
  > ci-results.jsonl

# Check exit code
if [ $? -eq 0 ]; then
  echo "Agent completed successfully"
fi
```

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

### Instantiate BashTool

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Create a new BashTool instance, optionally specifying an initial working directory and sandbox options.

```typescript
import { BashTool } from "./tools/bash";

const bash = new BashTool("/home/user/project", {
  sandboxMode: "shuru",
  sandboxSettings: { allowNet: true }
});
```

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

### Headless CI Integration with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Set the `GROK_API_KEY` environment variable and use `--prompt` with `--batch-api` for CI environments to run tests and report failures.

```bash
export GROK_API_KEY=xai-...
grok --prompt "Run tests and report failures" --batch-api
```

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

### Configure Reasoning for Grok Models

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/models.md

Initializes a provider and resolves the model runtime, which may include reasoning configuration options like reasoningEffort for supported models.

```typescript
import { createProvider, resolveModelRuntime } from "./grok/client";

const provider = createProvider(apiKey);
const runtime = resolveModelRuntime(provider, "grok-4.3");

// runtime includes providerOptions.xai.reasoningEffort if applicable
```

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

### computer_screenshot Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for capturing a PNG screenshot of a desktop window. Specify an output path or let the system handle it.

```typescript
{
  output_path?: string;   // Optional output path
  app?: string;           // Optional app name
  window_id?: string;     // Optional window ID
}
```

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

### Project-Specific Settings

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Define project-specific configurations in `.grok/settings.json`. This includes model selection, sandbox mode, network access, and hooks.

```json
{
  "model": "grok-4.3",
  "sandboxMode": "shuru",
  "sandboxSettings": {
    "allowNet": true,
    "allowedHosts": ["api.example.com"]
  },
  "hooks": {
    "PreToolUse": [...] 
  },
  "mcpServers": [...] 
}
```

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

### Build Project

Source: https://github.com/superagent-ai/grok-cli/blob/main/AGENTS.md

Compiles the TypeScript project into JavaScript for execution.

```bash
bun run build
```

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

### InstructionsLoaded Hook

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

This hook is fired when custom instructions from AGENTS.md are loaded.

```APIDOC
## InstructionsLoaded Hook

### Description
Fired when custom instructions (AGENTS.md) are loaded.

### Input Schema
```typescript
interface InstructionsLoadedHookInput {
  hook_event_name: "InstructionsLoaded";
  instructions: string;
  source: string;             // File path to AGENTS.md
  session_id?: string;
  cwd: string;
}
```
```

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

### Create a new session

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/storage.md

Use the `create` method to add a new session to the database. It requires workspace information and initial session configuration, returning the complete session details.

```typescript
async create(workspace: WorkspaceInfo, sessionInit: SessionInit): Promise<SessionInfo>
```

```typescript
interface SessionInit {
    title?: string;
    model: string;
    mode: AgentMode;
  }
```

```typescript
const store = new SessionStore();
const session = await store.create(
  {
    id: "workspace-123",
    canonicalPath: "/home/user/my-project",
    displayName: "my-project",
    scopeKey: "...",
    gitRoot: "/home/user/my-project",
    lastSeenAt: new Date(),
  },
  {
    title: "Fix authentication bug",
    model: "grok-4.3",
    mode: "agent",
  }
);
```

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

### Provide File Context with Directory

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/cli.md

Specify a directory to provide context for file analysis. This is useful when the target files are not in the current working directory.

```bash
grok -p "Review src/main.ts" --directory /path/to/repo
```

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

### delegate

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Launch a read-only background task. This is suitable for asynchronous operations that do not require immediate output.

```APIDOC
## delegate

### Description
Launch a read-only background task. This method is intended for asynchronous operations.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Request Body
- **agent** (string) - Optional - Currently only supports "explore".
- **description** (string) - Required - A label for the background task.
- **prompt** (string) - Required - Instructions for the background agent.

### Response
#### Success Response
- **success** (boolean) - Indicates if the delegation was successful.
- **delegation** (DelegationRun) - Optional - Details about the delegation run.
```

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

### Configure Agent Hooks

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Set up shell commands to run at specific agent lifecycle events. Use 'matcher' to filter events and 'hooks' to define commands. PreToolUse hooks can block actions with exit code 2.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint-before-edit.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/log-action.sh"
          }
        ]
      }
    ]
  }
}
```

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

### Pipe Data to Stdin

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Shows how to pipe data to a command's stdin, which is supported, contrasting with interactive input which is not.

```typescript
// Works: echo data is piped
await bash.execute("echo 'test' | grep test");

// Doesn't work: interactive input
// await bash.execute("read -p 'Enter: ' var");
```

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

### Verify Application with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

The `--verify` flag enables automatic detection of the build system and execution of smoke tests.

```bash
grok --verify     # Auto-detects build system and runs smoke tests
```

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

### computer_list_windows

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Lists all visible windows, optionally filtered by application name. Returns a string representation of the window list.

```APIDOC
## computer_list_windows

### Description
List visible windows.

### Parameters
#### Query Parameters
- **app** (string) - Optional - App filter

### Returns
`{ success: boolean; output: string }` with window list
```

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

### computer_screenshot

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Captures a PNG screenshot of a desktop window. The output path can be specified, or it will be handled by the system.

```APIDOC
## computer_screenshot

### Description
Capture PNG screenshot of desktop window.

### Parameters
#### Query Parameters
- **output_path** (string) - Optional - Output path
- **app** (string) - Optional - App name
- **window_id** (string) - Optional - Window ID

### Returns
`{ success: boolean; output: string }` with screenshot path
```

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

### Configure Hooks in user-settings.json

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Configure shell commands to execute at key agent lifecycle events by defining them in `~/.grok/user-settings.json`. The `matcher` specifies the shell type, and `hooks` contains the command details, including the script path and timeout.

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

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

### getToolDescription

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Returns a markdown-formatted description of the BashTool's capabilities, intended for use by agents.

```APIDOC
## getToolDescription(): string

Get the tool description for the agent.

### Returns
Markdown description of bash tool capabilities.
```

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

### Agent Constructor

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/agent.md

Initializes the Agent class with API credentials, model, and execution limits. Use this to set up a new agent instance for interacting with the Grok API.

```typescript
constructor(
  apiKey: string | undefined,
  baseURL: string,
  model: string | undefined,
  maxToolRounds: number,
  options?: AgentOptions
)
```

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

### computer_snapshot

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Captures a semantic accessibility snapshot of the desktop UI. This can be used to identify interactive elements and their properties.

```APIDOC
## computer_snapshot

### Description
Capture semantic accessibility snapshot of desktop UI.

### Parameters
#### Query Parameters
- **app** (string) - Optional - App name to scope
- **window_id** (string) - Optional - Window ID
- **interactive_only** (boolean) - Optional - Include only interactive elements (default: true)
- **include_bounds** (boolean) - Optional - Include element bounds
- **compact** (boolean) - Optional - Collapse single-child nodes
- **max_depth** (number) - Optional - Max tree depth
- **surface** (string) - Optional - "window", "focused", "menu", "menubar", "sheet", "popover", "alert"

### Returns
Accessibility tree with stable refs like `@e1`, `@e2`, etc.
```

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

### BashTool with Shuru Sandbox

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/bash-tool.md

Instantiates BashTool with Shuru sandbox mode enabled, configuring network access and allowed hosts. Commands executed with this instance run within an isolated microVM.

```typescript
const bash = new BashTool("/home/user/project", {
  sandboxMode: "shuru",
  sandboxSettings: {
    allowNet: true,
    allowedHosts: ["github.com"],
    cpus: 4,
    memory: 4096
  }
});

// Command runs in isolated VM with restrictions
const result = await bash.execute("npm install");
```

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

### computer_focus_window Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for bringing a specific window to the front. Can identify the window by ID, app name, or partial title.

```typescript
{
  window_id?: string;     // Window ID from computer_list_windows
  app?: string;           // App name
  title?: string;         // Partial window title
}
```

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

### Set Grok API Key via Command Line Argument

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Provides the Grok API key directly as a command-line argument. Useful for temporary or script-based configurations.

```bash
grok -k xai-...
```

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

### Backup Agent Database

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/storage.md

Copy the current agent database file to create a backup. This is useful for data safety and recovery.

```bash
cp ~/.grok/agent.db ~/.grok/agent.db.backup
```

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

### Define Custom Sub-Agents

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Configure optional custom foreground sub-agents by specifying their name, model, and instruction in the user settings. Names like 'general', 'explore', 'vision', 'verify', or 'computer' are reserved and cannot be used.

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

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

### Animate Image with Grok CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/README.md

Uses Grok CLI to animate a static image into a short video.

```bash
grok "Animate ./assets/cover.jpg into a 6 second cinematic push-in"
```

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

### Log All Tool Executions (Bash Hook)

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

This bash script logs the tool name, hook event, and current working directory to a file named 'tools.log'. It uses the 'PostToolUse' hook and a wildcard matcher to log all tool executions. No specific timeout is configured, so it defaults to 10 seconds.

```bash
#!/bin/bash
# ~/.grok/hooks/log-tools.sh

TOOL=$(jq -r '.tool_name' <<< "$1")
EVENT=$(jq -r '.hook_event_name' <<< "$1")
CWD=$(jq -r '.cwd' <<< "$1")

echo "[$(date '+%Y-%m-%d %H:%M:%S')] $EVENT: $TOOL in $CWD" >> ~/.grok/tools.log

exit 0
```

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.grok/hooks/log-tools.sh"
          }
        ]
      }
    ]
  }
}
```

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

### Run Grok CLI with Model Selection

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/README.md

Executes the Grok CLI with a specified model and prompt. Allows for fine-grained control over the AI model used for processing.

```bash
grok -m grok-4.3 --prompt "fix the test failures"
```

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

### Run Built CLI

Source: https://github.com/superagent-ai/grok-cli/blob/main/AGENTS.md

Executes the compiled Grok CLI application.

```bash
node dist/index.js
```

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

### Define Custom Sub-Agents

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/configuration.md

Configure custom foreground sub-agents by specifying their name, model, and instructions in user settings. Ensure names are not reserved keywords.

```json
{
  "subAgents": [
    {
      "name": "security-review",
      "model": "grok-4.3",
      "instruction": "Prioritize security implications and suggest concrete fixes."
    },
    {
      "name": "performance-audit",
      "model": "grok-4.20-non-reasoning",
      "instruction": "Focus on performance bottlenecks, memory usage, and optimization opportunities."
    }
  ]
}
```

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

### computer_wait Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for waiting for specific UI conditions on the desktop. Supports waiting for time, elements, windows, text, or menu states, with an optional timeout.

```typescript
{
  milliseconds?: number;  // Pause duration in ms
  element?: string;       // Wait for element ref to appear
  window?: string;        // Wait for window title to appear
  text?: string;          // Wait for text to appear in tree
  timeout_ms?: number;    // Timeout for waits
  app?: string;           // Scope app for waits
  menu?: boolean;         // Wait for menu to open
  menu_closed?: boolean;  // Wait for menu to close
}
```

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

### UserPromptSubmit Hook: Log all prompts

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/hooks.md

This bash script logs every user prompt to a file named 'grok-prompts.log' in the user's home directory. It includes the timestamp and the current working directory.

```bash
#!/bin/bash
# hooks/log-prompt.sh

PROMPT=$(jq -r '.user_prompt' <<< "$1")
CWD=$(jq -r '.cwd' <<< "$1")

echo "[$(date)] Prompt in $CWD: $PROMPT" >> ~/grok-prompts.log
```

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

### computer_type Parameters

Source: https://github.com/superagent-ai/grok-cli/blob/main/_autodocs/api-reference/tools.md

Defines parameters for typing text into a focused desktop element. Requires the element's accessibility reference and the text to be typed.

```typescript
{
  ref: string;            // Element ref from computer_snapshot
  text: string;           // Text to type
}
```
Tokens:
Raw