ACP CLI Commands
The praisonai 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
# Start ACP server with defaults
praisonai acp
# Start with specific workspace
praisonai acp --workspace /path/to/project
# Start with custom agent
praisonai 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
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')"
