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

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

# 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

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

# 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

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

# 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

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

# 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

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

# 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

# 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

# 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

# Check if language server is installed
which pylsp

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

ACP in read-only mode:

bash

# Check workspace permissions
ls -la ./workspace

# Verify ACP status
praisonai debug acp status

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

Debug CLI

Overview

Commands

debug interactive

debug lsp

debug acp

debug trace

JSON Output Format

Use Cases

CI/CD Testing

Troubleshooting

Performance Analysis

Operational Notes

Prerequisites

Exit Codes

Troubleshooting

Related