Grok CLI Integration

Run an Agent through your xAI subscription by delegating turns to the grok CLI. The Agent sends each turn to grok, which uses your xAI subscription login — no XAI_API_KEY required.

Quick Start

Install the Grok CLI

npm install -g @vibe-kit/grok-cli
grok --version
grok login

Run an Agent through Grok

from praisonaiagents import Agent

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

cli_backend= is deprecated (removal in 2.0.0). Prefer runtime="grok-cli" — see Runtime Selection.

How It Works

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.

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:

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:

framework: praisonai
agents:
  assistant:
    role: Helpful assistant
    cli_backend: grok-cli

Best Practices

Raise the timeout for long turns

The default timeout_ms is 5 minutes. For long-running turns, override it:

agent = Agent(cli_backend={"id": "grok-cli", "overrides": {"timeout_ms": 600000}})

Attach images when needed

Pass image paths and the backend forwards each as --image <path>. Useful for visual tasks the model can inspect.

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.

Codex CLI

Delegate Agent turns to OpenAI’s Codex CLI using your ChatGPT subscription.

Gemini CLI

Delegate Agent turns to Google’s Gemini CLI using your Google account.

Claude Code

The flagship CLI backend — works with Claude Pro / Max subscriptions.

CLI Backend Protocol

How CLI backends plug into the Agent API.

​Quick Start

​How It Works

​Use as Agent Backend

​Backend Configuration

​Backend CLI Flags

​Session Resume

​Configuration Surfaces

​Best Practices

​Robustness (PR #4111)

​Related

Codex CLI

Gemini CLI

Claude Code

CLI Backend Protocol

Quick Start

How It Works

Use as Agent Backend

Backend Configuration

Backend CLI Flags

Session Resume

Configuration Surfaces

Best Practices

Robustness (PR #4111)

Related