> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok CLI Integration

> Delegate Agent turns to xAI's Grok CLI using your subscription — no API key needed

Run an Agent through your xAI subscription by delegating turns to the `grok` CLI.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Grok CLI Backend"
        A[🧑 Agent] --> B[🔌 cli_backend='grok-cli']
        B --> C[💻 grok -p]
        C --> D[✅ Response]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef backend fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class B backend
    class C process
    class D result
```

The Agent sends each turn to `grok`, which uses your xAI subscription login — no `XAI_API_KEY` required.

## Quick Start

**1. Install the Grok CLI**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
npm install -g @vibe-kit/grok-cli
grok --version
grok login
```

**2. Run an Agent through Grok**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    cli_backend="grok-cli",
)
agent.start("Hello")
```

> [!NOTE]
>
> `cli_backend=` is deprecated (removal in 2.0.0). Prefer `runtime="grok-cli"` — see [Runtime Selection](https://praison.ai/docs/features/runtime-selection.md).

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Grok as grok CLI

    User->>Agent: agent.start("Hello")
    Agent->>Grok: grok --always-approve -p "Hello"
    Grok-->>Agent: plain-text response
    Agent-->>User: response
```

Each turn spawns `grok` with your subscription session. No API key is passed.

***

## Use as Agent Backend

Delegate an Agent's LLM turns to `grok -p` instead of the xAI API — uses your xAI subscription.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="assistant", cli_backend="grok-cli")
agent.start("Hello")
```

### Backend Configuration

The `grok-cli` backend ships with this default configuration:

| Option | Type | Default | Description |
| - | - | - | - |
| `command` | `str` | `"grok"` | CLI command (must be on PATH) |
| `args` | `List[str]` | `["--always-approve", "--output-format", "plain"]` | Default flags passed on every turn |
| `output` | `str` | `"text"` | Output format expected from the CLI |
| `input` | `str` | `"single"` | Prompt is passed as a single `-p` argument |
| `timeout_ms` | `int` | `300000` | Subprocess timeout (5 minutes) |

***

### Backend CLI Flags

The backend builds the `grok` command with these flags:

| Flag | Purpose |
| - | - |
| `--always-approve` | Skip interactive approval prompts |
| `--output-format plain` | Return plain-text output |
| `--cwd <path>` | Working directory (defaults to `os.getcwd()`) |
| `--resume <session_id>` | Resume a prior session (only when `session.is_resume`) |
| `--system-prompt-override <text>` | Inject the Agent's system prompt |
| `--image <path>` | Attach one or more image files |
| `-p <prompt>` | The user turn (added last) |

***

## Session Resume

The backend forwards `--resume <session_id>` only when the session is a resume — it checks `session.is_resume` before adding the flag. First turns start fresh.

***

## Configuration Surfaces

Override the default timeout (or any config field) with the dict form:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    cli_backend={"id": "grok-cli", "overrides": {"timeout_ms": 60000}},
)
agent.start("Hello")
```

Declare it in YAML for versioned configuration:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai
agents:
  assistant:
    role: Helpful assistant
    cli_backend: grok-cli
```

***

## Best Practices

> [accordion] Authenticate once with grok login
>
> Run `grok login` before your first Agent turn. The backend uses whatever subscription session the CLI is signed into — no `XAI_API_KEY` needed.

> [accordion] Raise the timeout for long turns
>
> The default `timeout_ms` is 5 minutes. For long-running turns, override it:
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> agent = Agent(cli_backend={"id": "grok-cli", "overrides": {"timeout_ms": 600000}})
> ```

> [accordion] Attach images when needed
>
> Pass image paths and the backend forwards each as `--image <path>`. Useful for visual tasks the model can inspect.

> [accordion] Prefer runtime='grok-cli'
>
> `cli_backend=` still works but emits a `DeprecationWarning`. Use `runtime="grok-cli"` for the modern equivalent, or run `praisonai doctor fix --execute` to migrate YAML.

***

## Robustness (PR #4111)

* A subprocess `TimeoutError` is now returned as `CliBackendResult(error=...)` instead of escaping as an exception.
* On `CalledProcessError`, the CLI's actual stderr diagnostic is surfaced (previously only the exit status was shown).
* `--model` and cwd are threaded through, so scheduled runs can pin a model and run in a workspace.
* `CliSessionBinding.is_resume` is now set on the second turn of a session, so the resume branch runs instead of re-sending the system prompt every turn.

***

## Related

> [card] [Codex CLI](https://praison.ai/docs/code/codex-cli.md)
>
> Delegate Agent turns to OpenAI's Codex CLI using your ChatGPT subscription.

> [card] [Gemini CLI](https://praison.ai/docs/code/gemini-cli.md)
>
> Delegate Agent turns to Google's Gemini CLI using your Google account.

> [card] [Claude Code](https://praison.ai/docs/code/claude-code.md)
>
> The flagship CLI backend — works with Claude Pro / Max subscriptions.

> [card] [CLI Backend Protocol](https://praison.ai/docs/features/cli-backend-protocol.md)
>
> How CLI backends plug into the Agent API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.