> ## 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

<Steps>
  <Step title="Install the Grok CLI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    npm install -g @vibe-kit/grok-cli
    grok --version
    grok login
    ```
  </Step>

  <Step title="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](/docs/features/runtime-selection).
    </Note>
  </Step>
</Steps>

***

## 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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="Attach images when needed">
    Pass image paths and the backend forwards each as `--image <path>`. Useful for visual tasks the model can inspect.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## 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

<CardGroup cols={2}>
  <Card title="Codex CLI" icon="code" href="/docs/code/codex-cli">
    Delegate Agent turns to OpenAI's Codex CLI using your ChatGPT subscription.
  </Card>

  <Card title="Gemini CLI" icon="google" href="/docs/code/gemini-cli">
    Delegate Agent turns to Google's Gemini CLI using your Google account.
  </Card>

  <Card title="Claude Code" icon="message-bot" href="/docs/code/claude-code">
    The flagship CLI backend — works with Claude Pro / Max subscriptions.
  </Card>

  <Card title="CLI Backend Protocol" icon="plug" href="/docs/features/cli-backend-protocol">
    How CLI backends plug into the Agent API.
  </Card>
</CardGroup>