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.

Diagram

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

Quick Start

Install the Grok CLI

bash

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

Run an Agent through Grok

python

from praisonaiagents import Agent

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

How It Works

Diagram

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

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

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

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

Best Practices

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.

Raise the timeout for long turns

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

python

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.