Skip to main content
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

​
How It Works

StepComponentPurpose
1User/CLISpecifies backend via flag or YAML
2ResolverFactory pattern for backend creation
3BackendProtocol implementation (e.g., ClaudeCodeBackend)
4ProcessExternal CLI subprocess execution
5ResultParsed response returned to Agent

​
Configuration Surfaces

​
The cli_backend YAML Field

ShapeExampleBehavior
Omitted(field absent)No backend used; Agent uses normal LLM client. No warning logged.
Stringcli_backend: claude-codeResolves via resolve_cli_backend("claude-code")
Dictcli_backend: {id: claude-code, overrides: {timeout_ms: 60000}}Resolves via resolve_cli_backend("claude-code", overrides={...})
Dict missing idcli_backend: {overrides: {...}}Returns None + logged warning. Does not raise.
Unknown idcli_backend: nopeReturns None + logged warning. Does not raise.
Invalid type (e.g. 123)cli_backend: 123Returns None + logged warning. Does not raise.

​
Built-in Backend: claude-code

The claude-code backend executes commands via the Claude Code CLI with these default settings:
OptionTypeDefaultDescription
commandstr"claude"CLI command (must be on PATH)
argsList[str]["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--setting-sources", "user", "--permission-mode", "bypassPermissions"]Default arguments passed to CLI
resume_argsList[str]["-p", "--output-format", "stream-json", "--resume", "{session_id}"]Arguments for resuming sessions
outputstr"jsonl"Output format expected from CLI
inputstr"stdin"How to pass prompts to CLI
live_sessionstr"claude-stdio"Live session mode
model_argstr"--model"CLI argument for model selection
model_aliasesDict[str, str]{"opus": "claude-opus-4-5", "sonnet": "claude-sonnet-4-5", "haiku": "claude-haiku-3-5"}Model name shortcuts
session_argstr"--session-id"CLI argument for session ID
session_modestr"always"When to use sessions
session_id_fieldsList[str]["session_id"]Fields containing session ID
system_prompt_argstr"--append-system-prompt"CLI argument for system prompts
system_prompt_whenstr"first"When to add system prompts
image_argstr"--image"CLI argument for images
clear_envList[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_mcpboolTrueEnable MCP bundling
bundle_mcp_modestr"claude-config-file"MCP bundling mode
serializeboolTrueQueue operations to avoid conflicts
timeout_msint300000Subprocess timeout (5 minutes)

​
The --cli-backend CLI Flag

FlagTypeBehavior
--cli-backend BACKEND_IDstringChoices 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

CommandBehavior
praisonai backends listPrints each registered backend id on its own line
praisonai backendsSame as list (list is the default)
praisonai backends bogusPrints [red]Unknown backends subcommand: bogus[/red] and the list of valid subcommands

​
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:
  • 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

​
Best Practices

Use the YAML cli_backend: field for versioned, declarative configuration. Use --cli-backend flag for quick one-off commands and testing.
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 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). 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.

External CLI Integrations

Legacy class-based CLI integration approach

Agent Configuration

Core Agent configuration and usage patterns