# List all Python code blocks in docs
praisonai docs list

# Run all runnable Python blocks (dry-run first)
praisonai docs run --dry-run

# Execute with reports
praisonai docs run --report-dir ./reports

praisonai docs run [OPTIONS]

# Run with custom docs path
praisonai docs run --docs-path /path/to/docs

# Run only specific groups (top-level directories)
praisonai docs run --group models --group tools

# Run only quickstart docs
praisonai docs run --include "quickstart*"

# Run with 2-minute timeout per snippet
praisonai docs run --timeout 120

# Strict mode - fail if any blocks can't be run
praisonai docs run --mode strict

# Limit to first 10 snippets for quick check
praisonai docs run --max-snippets 10

# Use specific Python interpreter
praisonai docs run --python /path/to/python

praisonai docs run --dry-run

# 1. See what would run
praisonai docs run --dry-run --report-dir ./preview

# 2. Inspect
cat ./preview/report.json | jq '.results[] | select(.skip_reason=="Dry run") | {source_path, block_index, runnable_decision}'

# 3. Real run once satisfied
praisonai docs run --report-dir ./actual

praisonai docs list [OPTIONS]

# List available groups
praisonai docs list --groups

# List blocks in specific group
praisonai docs list --group models --code

<!-- praisonai: runnable=true timeout=120 require_env=OPENAI_API_KEY -->
```python
from praisonaiagents import Agent
agent = Agent(instructions="test")
agent.start()

### Available Directives

| Directive | Values | Description |
|-----------|--------|-------------|
| `runnable` | `true/false` | Force block to be runnable or skipped |
| `skip` | `true/false` | Skip this block entirely |
| `timeout` | seconds | Custom timeout for this block |
| `require_env` | `KEY1,KEY2` | Required environment variables |

## Reports

Reports are generated in the specified directory:

### CSV Report

The CSV report contains one row per item for easy filtering:

| Column | Description |
|--------|-------------|
| `suite` | "docs" |
| `group` | Top-level directory (e.g., "models", "tools") |
| `item_id` | Unique identifier |
| `source_path` | Path to doc file |
| `block_index` | Code block index in file |
| `status` | passed/failed/skipped/timeout/not_run |
| `duration_seconds` | Execution time |
| `error_message` | Error details if failed |
| `code_hash` | Content hash for change tracking |

### JSON Report Schema

```json
{
  "metadata": {
    "timestamp": "2026-01-09T11:30:00Z",
    "platform": "Darwin-23.0.0-arm64",
    "python_version": "3.11.0",
    "praisonai_version": "2.0.0",
    "docs_path": "/path/to/docs",
    "totals": {
      "passed": 10,
      "failed": 2,
      "skipped": 5,
      "timeout": 0,
      "not_run": 15
    }
  },
  "results": [
    {
      "item_id": "docs/quickstart.mdx::0",
      "source_path": "docs/quickstart.mdx",
      "block_index": 0,
      "language": "python",
      "line_start": 30,
      "line_end": 39,
      "runnable_decision": "heuristic_standalone",
      "status": "not_run",
      "skip_reason": "Dry run",
      "code_hash": "sha256:…"
    }
  ]
}

name: Docs Validation

on: [push, pull_request]

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: pip install praisonai
      
      - name: Validate docs code blocks
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          praisonai docs run \
            --docs-path ./docs \
            --report-dir ./reports \
            --no-stream
      
      - name: Upload reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: docs-validation-report
          path: ./reports/

- name: Preview docs code blocks (no execution)
  run: |
    praisonai docs run \
      --docs-path ./docs \
      --dry-run \
      --report-dir ./preview

- name: Comment discovery summary
  # Post the report.md as a PR comment so reviewers see what a full run would attempt

praisonai docs run-all [OPTIONS]

# Run all groups in parallel (default)
praisonai docs run-all

# Run sequentially for debugging
praisonai docs run-all --sequential

# Run with more workers for faster execution
praisonai docs run-all --workers 8

# CI-friendly output
praisonai docs run-all --ci

praisonai docs stats [OPTIONS]

# Show CLI command statistics
praisonai docs cli stats

# List all discovered CLI commands
praisonai docs cli list

# Validate all CLI commands from docs
praisonai docs cli run-all

# Validate with limited scope
praisonai docs cli run-all --max-items 10 --timeout 5

praisonai docs cli run-all [OPTIONS]

# Run all CLI commands in parallel (default)
praisonai docs cli run-all

# Validate first 10 commands for quick check
praisonai docs cli run-all --max-items 10

# Run with more workers for faster execution
praisonai docs cli run-all --workers 8

# CI-friendly output with proper exit codes
praisonai docs cli run-all --ci --timeout 5

# Run sequentially for debugging
praisonai docs cli run-all --sequential

praisonai docs cli list [OPTIONS]

# List all CLI commands
praisonai docs cli list

# List available groups
praisonai docs cli list --groups

# List only runnable commands
praisonai docs cli list --runnable

praisonai docs cli stats [OPTIONS]

CLI Commands Statistics
========================================
Total commands:    1463
Runnable:          933
Skipped:           530

By Group:
----------------------------------------
  databases              31/37   runnable
  monitoring              8/9    runnable
  root                  894/1417 runnable

praisonai docs cli report [REPORT_DIR] [OPTIONS]

# View latest report
praisonai docs cli report

# View specific report directory
praisonai docs cli report ./my-report

# JSON output for parsing
praisonai docs cli report --format json

name: CLI Docs Validation

on: [push, pull_request]

jobs:
  validate-cli-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: pip install praisonai
      
      - name: Validate CLI commands in docs
        run: |
          praisonai docs cli run-all \
            --docs-path ./docs/cli \
            --ci \
            --timeout 10
      
      - name: Upload reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cli-validation-report
          path: ~/Downloads/reports/docs-cli/