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

> 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.

<Note>
  Use `praisonai serve acp` for the unified command. The standalone `praisonai acp` still works but shows a deprecation warning.
</Note>

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Install with ACP support
pip install "praisonai[acp]"

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

## Command Reference

### Basic Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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)

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start in read-only mode (safest)
praisonai acp --workspace /my/project
```

### With Write Permissions

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Resume a specific session
praisonai acp --resume sess_abc123

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

### With Specific Model

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable debug logging (logs to stderr)
praisonai acp --debug

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

### Approval Modes

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "command": "praisonai",
  "args": ["acp", "--workspace", "${projectDir}"]
}
```

### VSCode

Add to your VSCode settings:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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

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

### 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Verify ACP package is installed
python -c "import acp; print('ACP installed')"

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

### Debug Connection Issues

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run with debug logging
praisonai acp --debug 2>acp.log

# Check the log file
cat acp.log
```

### Verify API Keys

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

* [ACP Python API](/docs/acp) - Code-based usage
* [MCP Server](/docs/cli/mcp-server) - Model Context Protocol server
* [Serve Command](/docs/cli/serve) - HTTP API server