Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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)

# 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

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

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

​
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

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