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

# Debug CLI

> Debug commands for testing LSP, ACP, and interactive mode non-interactively

## Overview

The Debug CLI provides commands for testing and debugging the interactive coding assistant features without entering interactive mode. This is useful for CI/CD pipelines, automated testing, and troubleshooting.

## Commands

### debug interactive

Run a single interactive turn non-interactively:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai debug interactive -p "PROMPT" [OPTIONS]
```

**Options:**

| Option              | Description                         |
| ------------------- | ----------------------------------- |
| `-p, --prompt TEXT` | Prompt to execute (required)        |
| `--json`            | Output structured JSON trace        |
| `--lsp`             | Enable LSP code intelligence        |
| `--acp`             | Enable ACP action orchestration     |
| `--approval MODE`   | Approval mode: manual, auto, scoped |
| `--workspace PATH`  | Workspace root directory            |
| `--timeout SECONDS` | Max execution time (default: 60)    |

**Example:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple prompt
praisonai debug interactive -p "What is 2+2?"

# With LSP and JSON output
praisonai debug interactive -p "List all functions in main.py" --lsp --json

# With ACP for file operations
praisonai debug interactive -p "Create a hello.py file" --acp --approval auto --json
```

### debug lsp

Direct LSP probes for code intelligence:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai debug lsp SUBCOMMAND [OPTIONS]
```

**Subcommands:**

| Subcommand                 | Description             |
| -------------------------- | ----------------------- |
| `status`                   | Show LSP server status  |
| `symbols FILE`             | List symbols in file    |
| `definition FILE:LINE:COL` | Get definition location |
| `references FILE:LINE:COL` | Get references          |
| `diagnostics FILE`         | Get diagnostics         |

**Options:**

| Option             | Description                         |
| ------------------ | ----------------------------------- |
| `--language LANG`  | Language (python, javascript, etc.) |
| `--json`           | Output JSON format                  |
| `--workspace PATH` | Workspace root                      |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check LSP status
praisonai debug lsp status

# List symbols in a file
praisonai debug lsp symbols main.py --json

# Find definition
praisonai debug lsp definition main.py:10:5

# Find references
praisonai debug lsp references main.py:10:5 --json

# Get diagnostics
praisonai debug lsp diagnostics main.py
```

### debug acp

Direct ACP probes for action orchestration:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai debug acp SUBCOMMAND [OPTIONS]
```

**Subcommands:**

| Subcommand          | Description                            |
| ------------------- | -------------------------------------- |
| `status`            | Show ACP status                        |
| `plan -p "PROMPT"`  | Generate action plan without executing |
| `apply -p "PROMPT"` | Execute action plan                    |

**Options:**

| Option             | Description        |
| ------------------ | ------------------ |
| `--json`           | Output JSON format |
| `--approval MODE`  | Approval mode      |
| `--workspace PATH` | Workspace root     |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check ACP status
praisonai debug acp status

# Generate plan only (dry-run)
praisonai debug acp plan -p "Create a new Python file" --json

# Apply plan with auto-approval
praisonai debug acp apply -p "Create hello.py" --approval auto --json
```

### debug trace

Trace recording and replay:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai debug trace SUBCOMMAND [OPTIONS]
```

**Subcommands:**

| Subcommand         | Description                        |
| ------------------ | ---------------------------------- |
| `record -o FILE`   | Record interactive session to file |
| `replay FILE`      | Replay recorded session            |
| `diff FILE1 FILE2` | Compare two traces                 |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Record a session
praisonai debug trace record -o session.json

# Replay a session
praisonai debug trace replay session.json --json

# Compare traces
praisonai debug trace diff session1.json session2.json
```

## JSON Output Format

When using `--json`, the output follows this structure:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "version": "1.0",
  "timestamp": "2024-12-31T14:30:00Z",
  "prompt": "List all functions in main.py",
  "workspace": "/path/to/project",
  "runtime": {
    "lsp_enabled": true,
    "lsp_ready": true,
    "acp_enabled": false,
    "acp_ready": false
  },
  "trace": {
    "intent": "list_symbols",
    "lsp_calls": [
      {
        "method": "textDocument/documentSymbol",
        "params": {"uri": "file:///path/to/main.py"},
        "result": [...],
        "duration_ms": 45
      }
    ],
    "files_read": [],
    "tool_calls": [],
    "acp_actions": []
  },
  "response": {
    "text": "Found 5 functions in main.py...",
    "citations": [
      {"file": "main.py", "line": 10, "type": "symbol"}
    ]
  },
  "metrics": {
    "total_duration_ms": 1250,
    "lsp_duration_ms": 45,
    "llm_duration_ms": 1100
  }
}
```

## Use Cases

### CI/CD Testing

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Smoke test for interactive mode
praisonai debug interactive -p "What is 2+2?" --json --timeout 30

# Verify LSP is working
praisonai debug lsp status --json | jq '.overall_status'

# Test file creation flow
praisonai debug acp apply -p "Create test.py" --approval auto --json
```

### Troubleshooting

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check why LSP isn't working
praisonai debug lsp status

# Verify ACP can create files
praisonai debug acp plan -p "Create a file" --json

# Record a failing session for analysis
praisonai debug trace record -o debug_session.json
```

### Performance Analysis

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Measure LSP response time
praisonai debug lsp symbols large_file.py --json | jq '.duration_ms'

# Compare before/after optimization
praisonai debug trace diff before.json after.json
```

## Operational Notes

### Prerequisites

* `OPENAI_API_KEY` or other LLM API key must be set
* For LSP: language server must be installed (e.g., `pylsp`)
* For ACP: workspace must be writable

### Exit Codes

| Code | Meaning         |
| ---- | --------------- |
| 0    | Success         |
| 1    | General error   |
| 2    | Timeout         |
| 3    | LSP unavailable |
| 4    | ACP unavailable |

### Troubleshooting

**LSP not starting:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check if language server is installed
which pylsp

# Install Python language server
pip install python-lsp-server
```

**ACP in read-only mode:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check workspace permissions
ls -la ./workspace

# Verify ACP status
praisonai debug acp status
```

## Related

* [Agent-Centric Tools](/cli/agent-tools) - Tools powered by LSP/ACP
* [Interactive Runtime](/cli/interactive-runtime) - Runtime configuration
* [Doctor](/cli/doctor) - Health checks including LSP/ACP