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:

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:

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

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:

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

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:

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

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:

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

{
  "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

# 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

# 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

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

# Check if language server is installed
which pylsp

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

ACP in read-only mode:

# Check workspace permissions
ls -la ./workspace

# Verify ACP status
praisonai debug acp status

Related

• Agent-Centric Tools - Tools powered by LSP/ACP
• Interactive Runtime - Runtime configuration
• Doctor - Health checks including LSP/ACP