Praison AI

ACP CLI

CLI commands for Agent Client Protocol (ACP) server

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.

Quick Start

bash
# 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

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

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

Command Reference

Basic Usage

bash
praisonai acp [OPTIONS]

All Options

OptionShortDescriptionDefault
--workspace-wWorkspace root directoryCurrent directory
--agent-aAgent name or configuration filedefault
--agentsMulti-agent configuration YAML fileNone
--routerEnable router agent for task delegationDisabled
--model-mLLM model to useNone (uses default)
--resume-rResume session by IDNone
--lastResume the last session (use with --resume)Disabled
--approveApproval mode: manual, auto, scopedmanual
--read-onlyRead-only mode (no file writes)Enabled
--allow-writeAllow file write operationsDisabled
--allow-shellAllow shell command executionDisabled
--allow-networkAllow network requestsDisabled
--debugEnable debug logging to stderrDisabled
--profileUse named profile from configNone

Usage Examples

Minimal (Read-Only Mode)

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

With Write Permissions

bash
# 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

bash
# 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

bash
# Resume a specific session
praisonai acp --resume sess_abc123

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

With Specific Model

bash
# 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

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

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

Approval Modes

bash
# 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):

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:

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

VSCode

Add to your VSCode settings:

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

Environment Variables

VariableDescription
OPENAI_API_KEYOpenAI API key
ANTHROPIC_API_KEYAnthropic API key
GOOGLE_API_KEYGoogle AI API key
PRAISONAI_ACP_DEBUGEnable debug mode (1 or true)
PRAISONAI_ACP_WORKSPACEDefault 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

Permission Levels

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

Best Practices

bash
# 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

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

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

Debug Connection Issues

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

# Check the log file
cat acp.log

Verify API Keys

bash
# 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')"

Related