rpi

A non-interactive CLI agent that wraps the Claude Agent SDK. Designed for headless, scriptable use — pipe in a prompt, get structured output back.

Install

npm install -g @catalyst5010/rpi-cli

Build from source

From the monorepo root:

pnpm install
pnpm --filter @catalyst5010/rpi-cli build

The binary is at packages/cli/dist/cli.js and registered as rpi in package.json#bin.

Usage

# Basic prompt
rpi "Explain the builder pattern in TypeScript"

# Pipe from stdin
echo "Summarize this file" | rpi

# Continue the most recent session
rpi -c "What was the last thing we discussed?"

# Resume a specific session
rpi -r <session-id> "Continue from where we left off"

# Use a specific model
rpi --model opus "Write a haiku about recursion"

# Structured JSON output
rpi --output-format json --json-schema '{"type":"object","properties":{"name":{"type":"string"}}}' "Extract the author name from README.md"

# Stream all SDK messages as newline-delimited JSON
rpi --output-format stream-json "List the files in src/"

# Custom system prompt
rpi --system-prompt "You are a Go expert." "Review this function"

# Append to the default system prompt
rpi --append-system-prompt "Always respond in Spanish." "What is 2+2?"

# Limit turns and budget
rpi --max-turns 5 --max-budget-usd 0.50 "Refactor cli.ts"

# Skip all permission prompts (use with caution)
rpi --dangerously-skip-permissions "Delete all .tmp files"

Options Reference

General

| Flag | Description | |------|-------------| | -h, --help | Show help message | | -v, --version | Show version number | | -p, --print | Print mode (default, accepted for compatibility) | | --verbose | Verbose output |

Session

| Flag | Description | |------|-------------| | -c, --continue | Continue the most recent conversation | | -r, --resume <id> | Resume a specific session by ID | | --session-id <id> | Use a specific session ID (UUID) | | --fork-session | Fork session when resuming | | --no-session-persistence | Disable session persistence |

--continue and --resume are mutually exclusive.

Model

| Flag | Description | |------|-------------| | --model <model> | Model to use | | --fallback-model <model> | Fallback model if primary is unavailable |

Model aliases: sonnet → claude-sonnet-4-6, opus → claude-opus-4-6, haiku → claude-haiku-4-5-20251001. You can also pass a full model ID directly.

Permissions

| Flag | Description | |------|-------------| | --permission-mode <mode> | Permission mode | | --dangerously-skip-permissions | Skip all permission prompts |

Valid permission modes: default, acceptEdits, bypassPermissions, plan, dontAsk.

The default permission mode when none is specified is acceptEdits.

--dangerously-skip-permissions sets bypassPermissions mode with the safety flag enabled.

System Prompt

| Flag | Description | |------|-------------| | --system-prompt <text> | Custom system prompt (replaces default) | | --system-prompt-file <path> | Load system prompt from a file | | --append-system-prompt <text> | Append text to the default system prompt | | --append-system-prompt-file <path> | Append file contents to the default prompt |

--system-prompt and --system-prompt-file are mutually exclusive. The --append-* variants can be combined with each other and extend either a custom or the default prompt.

Output

| Flag | Description | |------|-------------| | --output-format <format> | Output format: text, json, stream-json | | --input-format <format> | Input format: text, stream-json | | --json-schema <schema> | JSON schema string for structured output |

See Output Modes for details.

Limits

| Flag | Description | |------|-------------| | --max-turns <n> | Maximum conversation turns | | --max-budget-usd <n> | Maximum budget in USD |

Tools

| Flag | Description | |------|-------------| | --tools <list> | Comma-separated tool list, or "default" | | --allowedTools <list> | Tools that auto-execute without prompting | | --disallowedTools <list> | Tools removed from model context |

Default tools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, AskUserQuestion.

Bridge (Human-in-the-Loop)

| Flag | Environment Variable | Description | |------|---------------------|-------------| | --bridge-endpoint <url> | RPI_BRIDGE_ENDPOINT | Bridge service URL | | --bridge-api-key <key> | RPI_BRIDGE_API_KEY | Bridge API key | | --bridge-topic <topic> | RPI_BRIDGE_TOPIC | Notification topic |

All three values must be provided (via flags or env vars) to enable bridge integration. When enabled, AskUserQuestion tool calls are routed through the bridge service, which sends push notifications to subscribed human operators and waits for a response.

Configuration

| Flag | Description | |------|-------------| | --add-dir <dir> | Additional working directories (repeatable) | | --mcp-config <path> | MCP server config file (JSON) | | --agent <name> | Agent name for the main thread | | --setting-sources <list> | Comma-separated setting sources: user, project, local | | --debug | Enable debug mode | | --include-partial-messages | Include partial streaming events | | --betas <list> | Comma-separated beta features |

Output Modes

The CLI separates content from metadata:

• stdout — pipeable output (assistant text, JSON results)
• stderr — tool invocations, result metadata (turns, cost)

text (default)

Assistant text content is written to stdout. Tool use events appear on stderr as [tool] <name>. Completion metadata appears on stderr as [done] <turns> turns, $<cost>.

json

Only the final result object is written to stdout as {"result": "..."}. Metadata still goes to stderr.

stream-json

Every SDK message is written to stdout as newline-delimited JSON. Useful for building pipelines or integrating with other tools. Metadata still goes to stderr.

When --json-schema is provided without an explicit --output-format, the mode defaults to json.

Environment Variables

| Variable | Description | |----------|-------------| | RPI_BRIDGE_ENDPOINT | Bridge service URL (fallback for --bridge-endpoint) | | RPI_BRIDGE_API_KEY | Bridge API key (fallback for --bridge-api-key) | | RPI_BRIDGE_TOPIC | Bridge notification topic (fallback for --bridge-topic) |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Agent completed successfully | | 1 | Agent failed, invalid arguments, or missing prompt |