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

# Batch

> Run multiple PraisonAI scripts at once for quick debugging and testing

The `praisonai batch` command discovers and runs all Python files containing PraisonAI imports in a directory. It's designed for quick debugging and testing of multiple scripts at once.

## Basic Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run all PraisonAI scripts in current directory
praisonai batch

# Include subdirectories
praisonai batch --sub

# Limit recursion depth
praisonai batch --sub --depth 2
```

## Key Features

* **Auto-discovery**: Finds all `.py` files with `from praisonaiagents` or `from praisonai` imports
* **Server exclusion**: Automatically excludes server scripts (uvicorn, Flask, streamlit, etc.) that would hang
* **Agent filtering**: Filter by agent type (Agent, Agents, Workflow)
* **CI integration**: Machine-readable output for automated pipelines
* **Parallel execution**: Run multiple scripts concurrently
* **Report generation**: JSON, Markdown, and CSV reports

## Options

| Option            | Description                                       |
| ----------------- | ------------------------------------------------- |
| `--path, -p`      | Path to search (default: current directory)       |
| `--sub, -r`       | Include subdirectories                            |
| `--depth, -d`     | Maximum recursion depth (only with --sub)         |
| `--timeout, -t`   | Per-script timeout in seconds (default: 60)       |
| `--parallel`      | Run in parallel with async reporting              |
| `--workers, -w`   | Max parallel workers (default: 4)                 |
| `--server`        | Run only server scripts with 10s timeout          |
| `--filter, -f`    | Filter by type: 'agent', 'agents', or 'workflow'  |
| `--ci`            | CI-friendly output (no colors, proper exit codes) |
| `--quiet, -q`     | Minimal output                                    |
| `--fail-fast, -x` | Stop on first failure                             |
| `--include-tests` | Include test files (test\_\*.py, \*\_test.py)     |
| `--no-report`     | Skip report generation                            |
| `--report-dir`    | Custom report directory                           |

## Server Script Handling

By default, the batch command **excludes server scripts** that would hang during execution. Server scripts are detected by patterns like:

* `uvicorn.run()` - ASGI servers
* `.launch()` - PraisonAI agent APIs, Gradio interfaces
* `app.run()` - Flask applications
* `import streamlit` - Streamlit apps
* `import gradio` - Gradio apps
* `FastAPI()`, `Flask()` - Web frameworks

### Running Server Scripts

Use the `--server` flag to run **only** server scripts with a 10-second timeout:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run only server scripts (10s timeout each)
praisonai batch --server

# Server scripts in subdirectories
praisonai batch --server --sub
```

This is useful for smoke-testing that server scripts start correctly.

## Filtering by Agent Type

Filter scripts by the PraisonAI components they use:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Only scripts using Agent class
praisonai batch --filter agent

# Only scripts using Agents/PraisonAIAgents (multi-agent)
praisonai batch --filter agents

# Only scripts using Workflow
praisonai batch --filter workflow
```

## CI Integration

The `--ci` flag provides machine-readable output suitable for CI/CD pipelines:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# CI-friendly output
praisonai batch --ci

# CI with proper exit codes
praisonai batch --ci --fail-fast
```

CI mode features:

* No emoji/color output (plain text)
* Proper exit codes (0 = success, 1 = failures, 2 = errors)
* Machine-parseable summary

### Example CI Output

```
============================================================
PraisonAI Batch Runner
============================================================
Path: /path/to/scripts
Recursive: False
Timeout: 60s
Scripts: 5
Reports: /Users/user/Downloads/reports/batch/20240115_120000

[1/5] Running: agent_example.py
  PASS PASSED (2.34s)
[2/5] Running: multi_agent.py
  PASS PASSED (5.67s)
[3/5] Running: broken_script.py
  FAIL FAILED (0.12s)
     Error: ImportError: No module named 'missing'

============================================================
SUMMARY
============================================================
  PASSED:  2
  FAILED:  1
  SKIPPED: 0
  TIMEOUT: 0
  -----------------
  TOTAL:   3
============================================================
Reports: /Users/user/Downloads/reports/batch/20240115_120000
```

## Parallel Execution

Run scripts concurrently for faster execution:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run in parallel with 4 workers (default)
praisonai batch --parallel

# Custom worker count
praisonai batch --parallel --workers 8

# Parallel with CI output
praisonai batch --parallel --ci
```

## Subcommands

### List Scripts

List discovered scripts without running them:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List all discovered scripts
praisonai batch list

# List with subdirectories
praisonai batch list --sub

# Show available groups only
praisonai batch list --groups
```

### Show Statistics

Display statistics about discovered scripts:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai batch stats
praisonai batch stats --sub
```

Output includes counts by:

* Group (directory)
* Runnable status
* Agent type (Agent, Agents, Workflow)

### View Reports

View the latest execution report:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Summary view
praisonai batch report

# Show failures only
praisonai batch report --format failures

# Full details
praisonai batch report --format full

# Specific report directory
praisonai batch report --dir ~/Downloads/reports/batch/20240115_120000
```

## Script Directives

Control script behavior with comment directives:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# praisonai: skip=true
# praisonai: timeout=120
# praisonai: require_env=OPENAI_API_KEY,ANTHROPIC_API_KEY
# praisonai: xfail=Known issue with API

from praisonaiagents import Agent
# ... rest of script
```

| Directive               | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `skip=true`             | Skip this script                                 |
| `timeout=N`             | Custom timeout in seconds                        |
| `require_env=KEY1,KEY2` | Required environment variables                   |
| `xfail=reason`          | Expected to fail (mark as xfail instead of fail) |

## Reports

Reports are saved to `~/Downloads/reports/batch/<timestamp>/` by default:

* `report.json` - Full JSON report
* `report.md` - Markdown summary
* `report.csv` - CSV for spreadsheet analysis
* `logs/` - Individual script output logs

## Examples

### Basic Testing

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Test all scripts in examples folder
praisonai batch --path ./examples

# Test with subdirectories, 2 levels deep
praisonai batch --path ./examples --sub --depth 2
```

### CI Pipeline

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# GitHub Actions / GitLab CI
praisonai batch --ci --fail-fast --timeout 30

# With parallel execution
praisonai batch --ci --parallel --workers 4
```

### Development Workflow

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Quick test of agent scripts only
praisonai batch --filter agent --timeout 30

# Test multi-agent workflows
praisonai batch --filter agents --sub

# Smoke test server scripts
praisonai batch --server
```

## Exit Codes

| Code | Meaning                                            |
| ---- | -------------------------------------------------- |
| 0    | All scripts passed                                 |
| 1    | One or more scripts failed or timed out            |
| 2    | Configuration error (invalid path, invalid filter) |