CLI Backend Protocol

Plug an external CLI (Claude Code, future: Codex, Gemini) in as a first-class Agent backend

from praisonaiagents import Agent

agent = Agent(name="cli-worker", instructions="Run this turn via an external CLI backend.", runtime="claude-code")
agent.start("Implement the login form.")

The user runs an agent turn; the CLI backend resolver spawns the external CLI and returns the result through the same Agent API.

CLI Backends let you run an agent’s turn through an external CLI tool (like Claude Code) instead of a Python LLM client, while keeping the same Agent/Task API.

Quick Start

1. Simplest: CLI flag

   praisonai "Refactor utils.py" --cli-backend claude-code

2. Declarative: YAML

   framework: praisonai
   topic: coding
   roles:
     coder:
       role: Code refactorer
       goal: Refactor Python modules
       backstory: Senior engineer
       cli_backend: claude-code   # string form
       tasks:
         refactor:
           description: Refactor utils.py
           expected_output: Refactored code

3. YAML with overrides

   roles:
     coder:
       role: Code refactorer
       goal: Refactor Python modules
       backstory: Senior engineer
       cli_backend:
         id: claude-code
         overrides:
           timeout_ms: 60000
       tasks:
         refactor:
           description: Refactor utils.py
           expected_output: Refactored code

4. Discover what's registered

   praisonai backends list
   # claude-code
   # codex-cli
   # grok-cli
   # gemini-cli

How It Works

Permission modes (Claude Code backend)

To opt into bypass:

export PRAISONAI_CLAUDE_BYPASS_PERMISSIONS=1

from praisonai.cli_backends.claude import ClaudeCodeBackend

backend = ClaudeCodeBackend(config={...}, unsafe=True)

With only unsafe=True or only the env var set, the backend overrides to default mode and logs a warning.

Configuration Surfaces

Observability

Confirm that PraisonAI is skipping the LiteLLM HTTP call and delegating to a CLI subprocess.

A user adopts cli_backend="codex-cli" and wants proof delegation is actually happening. They set PRAISONAI_CLI_BACKEND_DEBUG=1, enable cli_backend_tracer, and see one log line per turn — with the prompt already redacted so the log stream is safe to ship to an aggregator. If it silently isn’t delegating, no log line appears — and they know something is wrong at config time.

Env var

export PRAISONAI_CLI_BACKEND_DEBUG=1
# or the standard knob
export LOGLEVEL=DEBUG

Plugin

pip install praisonai-plugins
praisonai plugins enable cli_backend_tracer

Hook (programmatic)

from praisonaiagents import Agent
from praisonaiagents.hooks import HookRegistry, HookEvent, HookResult

registry = HookRegistry()

@registry.on(HookEvent.CLI_BACKEND_EXECUTE)
def trace(event_data):
    print(f"{event_data.backend} → {event_data.command}")
    return HookResult.allow()

agent = Agent(name="assistant", cli_backend="codex-cli", hooks=registry)
agent.start("Refactor utils.py")

See Hook Events → CLI Backend Events for the full payload reference. The command field is redacted at the serialisation boundary — user prompts and system instructions never leak into log sinks.

The cli_backend YAML Field

Framework Compatibility

cli_backend is a runtime feature — it works only with an adapter whose SUPPORTS_RUNTIME_FEATURES = True (the built-in praisonai adapter has it).

Third-party adapters opt in by setting SUPPORTS_RUNTIME_FEATURES = True on their subclass — see Capability Flags.

Using cli_backend in Python

from praisonaiagents import Agent

# 1. String form — same as YAML
agent = Agent(
    name="Refactorer",
    instructions="Refactor Python files cleanly",
    cli_backend="claude-code",
)

agent.start("Refactor utils.py")

# 2. Dict form with overrides — now works in Python too (PR #1797)
agent = Agent(
    name="Refactorer",
    instructions="Refactor Python files cleanly",
    cli_backend={
        "id": "claude-code",
        "overrides": {"timeout_ms": 60000},
    },
)

# 3. Pre-resolved instance — full control
from praisonai.cli_backends import resolve_cli_backend

backend = resolve_cli_backend("claude-code", overrides={"timeout_ms": 60000})

agent = Agent(
    name="Refactorer",
    cli_backend=backend,
)

Built-in backends

Four backends ship registered out of the box. Each routes through a CLI that owns its own subscription/OAuth session, so no raw API key is needed.

Select any of them by ID — the shape is identical to claude-code:

cli_backend: codex-cli   # ChatGPT subscription
cli_backend: grok-cli    # xAI subscription
cli_backend: gemini-cli  # Google account

from praisonaiagents import Agent

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

Built-in Backend: claude-code

The claude-code backend executes commands via the Claude Code CLI with these default settings:

The --cli-backend CLI Flag

The backends Subcommand

Custom Backends (Advanced)

Register your own CLI backend for custom tools:

from praisonai.cli_backends import register_cli_backend
from praisonaiagents import CliBackendConfig

def my_backend_factory():
    from my_pkg import MyBackend
    return MyBackend(config=CliBackendConfig(command="my-cli"))

register_cli_backend("my-backend", my_backend_factory)

After registering, praisonai backends list shows it, --cli-backend my-backend accepts it, and cli_backend: my-backend works in YAML.

CliBackendProtocol Reference

For backend authors implementing the protocol:

graph LR
    subgraph "CliBackendProtocol"
        A[config: CliBackendConfig] 
        B[async execute(...)]
        C[async stream(...)]
        D[capabilities()]
    end

    classDef protocol fill:#8B0000,stroke:#7C90A0,color:#fff

    class A,B,C,D protocol

• config: CliBackendConfig — Configuration object
• async def execute(prompt, *, session=None, images=None, system_prompt=None, **kwargs) -> CliBackendResult — Single execution
• async def stream(prompt, **kwargs) -> AsyncIterator[CliBackendDelta] — Streaming execution
• def capabilities() -> RuntimeCapabilityMatrix — Required (new). Returns the capability matrix for this backend.

Best Practices

cli_backend:
  id: claude-code
  overrides:
    timeout_ms: 60000  # 1 minute instead of 5

How this differs from --external-agent

Related