> ## 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.
# CLI Backend Protocol
> Plug an external CLI (Claude Code, future: Codex, Gemini) in as a first-class Agent backend
**Deprecated — use [Runtime Selection](/docs/features/runtime-selection) instead.** `cli_backend` still works through 2.0.0 but emits `DeprecationWarning`. For YAML migration, run `praisonai doctor fix --execute` (or the equivalent `praisonai doctor runtime --fix --execute`) — see [Runtime Config Migration](/docs/features/doctor-runtime-migration).
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Before
agent = Agent(instructions="...", cli_backend="claude-code")
# After
agent = Agent(instructions="...", runtime="claude-code")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "CLI Backend Flow"
A[📋 Agent Input] --> B[🧠 Resolver]
B --> C[🔌 Backend]
C --> D[💻 CLI Process]
D --> E[✅ Result]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef resolver fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef backend fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,color:#fff
classDef tool fill:#189AB4,color:#fff
class A input
class B resolver
class C,D backend
class E result
```
## Quick Start
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Refactor utils.py" --cli-backend claude-code
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai backends list
# claude-code
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Loader as YAML/Python loader
participant Validator as Framework check
participant Resolver as resolve_cli_backend_config
participant Backend as ClaudeCodeBackend
participant Agent
User->>Loader: cli_backend = "claude-code" (or dict)
Loader->>Validator: framework == "praisonai"?
alt framework is praisonai
Validator->>Resolver: pass-through
Resolver->>Backend: instantiate (or use cached)
Backend-->>Agent: ready to delegate turns
else any other framework
Validator-->>User: ValueError (fast fail)
end
```
| Step | Component | Purpose |
| ---- | --------- | ------------------------------------------------- |
| 1 | User/CLI | Specifies backend via flag or YAML |
| 2 | Resolver | Factory pattern for backend creation |
| 3 | Backend | Protocol implementation (e.g., ClaudeCodeBackend) |
| 4 | Process | External CLI subprocess execution |
| 5 | Result | Parsed response returned to Agent |
### Permission modes (Claude Code backend)
| Setting | Default (PR #2122) | Notes |
| ------------------------------- | ------------------ | ------------------------------- |
| `--permission-mode` | `default` | Was `bypassPermissions` |
| `ClaudeCodeBackend(unsafe=...)` | `False` | Set `True` + env var for bypass |
To opt into bypass:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_CLAUDE_BYPASS_PERMISSIONS=1
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{How do I want to configure a CLI backend?}
Q -->|Quickest, ad-hoc command| A[--cli-backend on the CLI]
Q -->|Versioned, per-role config| B[cli_backend in YAML - string form]
Q -->|Need to tweak timeouts/args| C[cli_backend in YAML - dict with overrides]
Q -->|Building a custom backend| D[register_cli_backend in Python]
classDef question fill:#6366F1,stroke:#7C90A0,color:#fff
classDef option fill:#189AB4,stroke:#7C90A0,color:#fff
class Q question
class A,B,C,D option
```
***
## The `cli_backend` YAML Field
| Shape | Example | Behavior |
| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Omitted | *(field absent)* | No backend used; Agent uses normal LLM client. No warning logged. |
| String | `cli_backend: claude-code` | Resolves via `resolve_cli_backend("claude-code")`. |
| Dict | `cli_backend: {id: claude-code, overrides: {timeout_ms: 60000}}` | Resolves via `resolve_cli_backend("claude-code", overrides={...})`. |
| Empty string | `cli_backend: ""` | **Raises** `ValueError("cli_backend string cannot be empty")`. |
| Dict missing `id` | `cli_backend: {overrides: {...}}` | **Raises** `ValueError("cli_backend dict must contain an 'id' field")`. |
| `overrides` not a dict | `cli_backend: {id: claude-code, overrides: "bad"}` | **Raises** `ValueError("cli_backend.overrides must be a dict")`. |
| Invalid type | `cli_backend: 123` | **Raises** `ValueError("cli_backend must be string, dict, or instance, got: int")`. |
| Unknown id | `cli_backend: nope` | Returns `None` + logged warning. (Registry lookup, unchanged.) |
***
## 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).
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{adapter SUPPORTS_RUNTIME_FEATURES?}
Q -->|True| OK[✅ cli_backend takes effect]
Q -->|False| FAIL[❌ ValueError at config validation]
classDef question fill:#6366F1,stroke:#7C90A0,color:#fff
classDef success fill:#10B981,stroke:#7C90A0,color:#fff
classDef error fill:#8B0000,stroke:#7C90A0,color:#fff
class Q question
class OK success
class FAIL error
```
| `framework` value | `cli_backend` behaviour |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `praisonai` (default) | Resolved and used to delegate every agent turn. |
| `crewai`, `autogen`, `autogen_v4`, `ag2` | **Raises** `ValueError: Runtime features (...) are not supported for framework=''. Use a framework whose adapter sets SUPPORTS_RUNTIME_FEATURES = True (e.g. framework='praisonai').` Validation runs before any agent starts, so no partial run is performed. |
Third-party adapters opt in by setting `SUPPORTS_RUNTIME_FEATURES = True` on their subclass — see [Capability Flags](/docs/features/framework-adapter-plugins#capability-flags).
This is a behaviour change in PR #1797 — previously `cli_backend` was silently ignored under non-praisonai frameworks. Now it fails loudly at config-load time. A follow-up fix ([PR #2004](https://github.com/MervinPraison/PraisonAI/pull/2004)) restored this validation for `framework: praisonai` — previously a regression caused all `cli_backend` configs to fail at validation regardless of framework.
***
## Using `cli_backend` in Python
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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},
},
)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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,
)
```
| Shape | Example | When to use |
| ---------- | --------------------------------------------------------------- | ---------------------------------------- |
| `str` | `cli_backend="claude-code"` | Quickest path. Matches YAML idiom. |
| `dict` | `cli_backend={"id": "claude-code", "overrides": {...}}` | Need timeout / args / model overrides. |
| instance | `cli_backend=resolve_cli_backend("claude-code", overrides=...)` | Pre-resolved once, reused across agents. |
| `callable` | `cli_backend=my_factory` | Factory function returning a backend. |
YAML and Python now accept the exact same shapes (was previously YAML-only for dict).
***
## Built-in Backend: `claude-code`
The `claude-code` backend executes commands via the Claude Code CLI with these default settings:
| Option | Type | Default | Description |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `command` | `str` | `"claude"` | CLI command (must be on PATH) |
| `args` | `List[str]` | `["-p", "--output-format", "stream-json", ..., "--permission-mode", "default"]` | Default permission mode is `default` (PR #2122; was `bypassPermissions`) |
| `resume_args` | `List[str]` | `["-p", "--output-format", "stream-json", "--resume", "{session_id}"]` | Arguments for resuming sessions |
| `output` | `str` | `"jsonl"` | Output format expected from CLI |
| `input` | `str` | `"stdin"` | How to pass prompts to CLI |
| `live_session` | `str` | `"claude-stdio"` | Live session mode |
| `model_arg` | `str` | `"--model"` | CLI argument for model selection |
| `model_aliases` | `Dict[str, str]` | `{"opus": "claude-opus-4-5", "sonnet": "claude-sonnet-4-5", "haiku": "claude-haiku-3-5"}` | Model name shortcuts |
| `session_arg` | `str` | `"--session-id"` | CLI argument for session ID |
| `session_mode` | `str` | `"always"` | When to use sessions |
| `session_id_fields` | `List[str]` | `["session_id"]` | Fields containing session ID |
| `system_prompt_arg` | `str` | `"--append-system-prompt"` | CLI argument for system prompts |
| `system_prompt_when` | `str` | `"first"` | When to add system prompts |
| `image_arg` | `str` | `"--image"` | CLI argument for images |
| `clear_env` | `List[str]` | `["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_OAUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CONFIG_DIR", "CLAUDE_CODE_OAUTH_TOKEN", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_RESOURCE_ATTRIBUTES", "GOOGLE_APPLICATION_CREDENTIALS", "AWS_PROFILE", "AWS_REGION", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"]` | Environment variables sanitized before subprocess |
| `bundle_mcp` | `bool` | `True` | Enable MCP bundling |
| `bundle_mcp_mode` | `str` | `"claude-config-file"` | MCP bundling mode |
| `serialize` | `bool` | `True` | Queue operations to avoid conflicts |
| `timeout_ms` | `int` | `300000` | Subprocess timeout (5 minutes) |
***
## The `--cli-backend` CLI Flag
| Flag | Type | Behavior |
| --------------------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `--cli-backend BACKEND_ID` | string | Choices populated dynamically from `list_cli_backends()`. Currently: `claude-code`. |
| `--cli-backend X --external-agent Y` | — | **Mutually exclusive** — argparse rejects with "not allowed with argument" |
| Unknown id (e.g. `--cli-backend bogus`) | — | Rejected by argparse with "invalid choice" |
***
## The `backends` Subcommand
| Command | Behavior |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| `praisonai backends list` | Prints each registered backend id on its own line |
| `praisonai backends` | Same as `list` (list is the default) |
| `praisonai backends bogus` | Prints `[red]Unknown backends subcommand: bogus[/red]` and the list of valid subcommands |
***
## Custom Backends (Advanced)
Register your own CLI backend for custom tools:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
**Breaking change:** `CliBackendProtocol` now requires a `capabilities() -> RuntimeCapabilityMatrix` method so the framework can validate capabilities at config time. Third-party backends must add this method. Without it, the backend will be treated as supporting only the reduced capability set (`tool_loop`, `basic_chat`, `simple_tools`).
***
## Best Practices
Use the YAML `cli_backend:` field for versioned, declarative configuration. Use `--cli-backend` flag for quick one-off commands and testing.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
cli_backend:
id: claude-code
overrides:
timeout_ms: 60000 # 1 minute instead of 5
```
Rather than monkey-patching, use the overrides system for custom timeouts.
The `cli_backend` field requires an adapter whose `SUPPORTS_RUNTIME_FEATURES = True` — the built-in `framework: praisonai` (the default) qualifies. PraisonAI validates this up front — if you try it with `crewai`, `autogen`, `autogen_v4`, or `ag2`, you'll get a `ValueError` immediately, before any agent runs.
The `--cli-backend` flag and `--external-agent` flag are mutually exclusive. Pick one approach:
* CLI Backends (new): Pluggable, configurable, YAML-supported
* External Agent (legacy): Class-based, limited configuration
The `claude-code` backend requires the `claude` CLI to be installed and accessible. Install via the Claude Code SDK or ensure it's in your system PATH.
***
## How this differs from `--external-agent`
The legacy `--external-agent claude` and `ClaudeCodeIntegration` class still work and are unchanged (see [External CLI Integrations](/docs/features/external-cli-integrations)). The CLI Backend Protocol is the **new pluggable** path: backends are registered by id, configured declaratively, and surfaced as a YAML field and `--cli-backend` flag.
***
## Related
Model-scoped runtime configuration (replaces cli\_backend)
Legacy class-based CLI integration approach
Core Agent configuration and usage patterns