ACP CLI Commands

The praisonai serve acp command starts an ACP server that enables IDEs and code editors to communicate with PraisonAI agents using JSON-RPC 2.0 over stdio.

Use praisonai serve acp for the unified command. The standalone praisonai acp still works but shows a deprecation warning.

Quick Start

# Start ACP server with defaults
praisonai serve acp

# Start with specific workspace
praisonai serve acp --workspace /path/to/project

# Start with custom agent
praisonai serve acp --agent my_agent.yaml

Installation

# Install with ACP support
pip install "praisonai[acp]"

# Or install the ACP package separately
pip install agent-client-protocol

Command Reference

Basic Usage

praisonai acp [OPTIONS]

All Options

Option	Short	Description	Default
`--workspace`	`-w`	Workspace root directory	Current directory
`--agent`	`-a`	Agent name or configuration file	`default`
`--agents`		Multi-agent configuration YAML file	None
`--router`		Enable router agent for task delegation	Disabled
`--model`	`-m`	LLM model to use	None (uses default)
`--resume`	`-r`	Resume session by ID	None
`--last`		Resume the last session (use with `--resume`)	Disabled
`--approve`		Approval mode: `manual`, `auto`, `scoped`	`manual`
`--read-only`		Read-only mode (no file writes)	Enabled
`--allow-write`		Allow file write operations	Disabled
`--allow-shell`		Allow shell command execution	Disabled
`--allow-network`		Allow network requests	Disabled
`--debug`		Enable debug logging to stderr	Disabled
`--profile`		Use named profile from config	None

Usage Examples

Minimal (Read-Only Mode)

# Start in read-only mode (safest)
praisonai acp --workspace /my/project

With Write Permissions

# Allow file writes
praisonai acp --workspace /my/project --allow-write

# Allow shell commands
praisonai acp --workspace /my/project --allow-write --allow-shell

With Custom Agent

# Use a custom agent configuration
praisonai acp --agent coding_assistant.yaml

# Use multi-agent setup with router
praisonai acp --agents team.yaml --router

Resume Previous Session

# Resume a specific session
praisonai acp --resume sess_abc123

# Resume the most recent session
praisonai acp --resume --last

With Specific Model

# Use GPT-4o
praisonai acp --model gpt-4o

# Use Claude
praisonai acp --model claude-3-5-sonnet-20241022

# Use Gemini
praisonai acp --model gemini/gemini-2.0-flash

Debug Mode

# Enable debug logging (logs to stderr)
praisonai acp --debug

# Combine with other options
praisonai acp --workspace /my/project --debug --allow-write

Approval Modes

# Manual approval (default) - user approves each action
praisonai acp --approve manual

# Auto approval - actions auto-approved (use with caution)
praisonai acp --approve auto

# Scoped approval - auto-approve within defined scope
praisonai acp --approve scoped

Editor Configuration

Zed Editor

Add to your Zed settings (~/.config/zed/settings.json):

{
  "assistant": {
    "version": "2",
    "default_model": {
      "provider": "praisonai",
      "model": "gpt-4o"
    }
  },
  "context_servers": {
    "praisonai": {
      "command": {
        "path": "praisonai",
        "args": ["acp", "--workspace", "."]
      }
    }
  }
}

JetBrains IDEs

Configure in Settings → Tools → AI Assistant:

{
  "command": "praisonai",
  "args": ["acp", "--workspace", "${projectDir}"]
}

VSCode

Add to your VSCode settings:

{
  "praisonai.acp.command": "praisonai",
  "praisonai.acp.args": ["acp", "--workspace", "${workspaceFolder}"]
}

Environment Variables

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`GOOGLE_API_KEY`	Google AI API key
`PRAISONAI_ACP_DEBUG`	Enable debug mode (`1` or `true`)
`PRAISONAI_ACP_WORKSPACE`	Default workspace path

Output Behavior

stdout: JSON-RPC 2.0 messages only (for IDE communication)
stderr: Logs and debug output (when --debug is enabled)

This separation ensures clean communication with IDEs while allowing debugging.

Security Considerations

By default, ACP runs in read-only mode for safety. Enable write/shell permissions only when needed.

Permission Levels

Read-only (default): Can read files, cannot modify anything
Allow-write: Can create and modify files within workspace
Allow-shell: Can execute shell commands (use with caution)
Allow-network: Can make network requests

Best Practices

# For code review (read-only)
praisonai acp --workspace /my/project

# For development (write access)
praisonai acp --workspace /my/project --allow-write

# For full automation (all permissions)
praisonai acp --workspace /my/project --allow-write --allow-shell --allow-network

Troubleshooting

Check ACP Installation

# Verify ACP package is installed
python -c "import acp; print('ACP installed')"

# If not installed
pip install "praisonai[acp]"

Debug Connection Issues

# Run with debug logging
praisonai acp --debug 2>acp.log

# Check the log file
cat acp.log

Verify API Keys

# Check if API keys are set
python -c "import os; print('OPENAI_API_KEY:', 'SET' if os.environ.get('OPENAI_API_KEY') else 'NOT SET')"

ACP Python API - Code-based usage
MCP Server - Model Context Protocol server
Serve Command - HTTP API server

​ACP CLI Commands

​Quick Start

​Installation

​Command Reference

​Basic Usage

​All Options

​Usage Examples

​Minimal (Read-Only Mode)

​With Write Permissions

​With Custom Agent

​Resume Previous Session

​With Specific Model

​Debug Mode

​Approval Modes

​Editor Configuration

​Zed Editor

​JetBrains IDEs

​VSCode

​Environment Variables

​Output Behavior

​Security Considerations

​Permission Levels

​Best Practices

​Troubleshooting

​Check ACP Installation

​Debug Connection Issues

​Verify API Keys

​Related

ACP CLI Commands

Quick Start

Installation

Command Reference

Basic Usage

All Options

Usage Examples

Minimal (Read-Only Mode)

With Write Permissions

With Custom Agent

Resume Previous Session

With Specific Model

Debug Mode

Approval Modes

Editor Configuration

Zed Editor

JetBrains IDEs

VSCode

Environment Variables

Output Behavior

Security Considerations

Permission Levels

Best Practices

Troubleshooting

Check ACP Installation

Debug Connection Issues

Verify API Keys

Related