Skip to main content
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

# 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

OptionDescription
--path, -pPath to search (default: current directory)
--sub, -rInclude subdirectories
--depth, -dMaximum recursion depth (only with —sub)
--timeout, -tPer-script timeout in seconds (default: 60)
--parallelRun in parallel with async reporting
--workers, -wMax parallel workers (default: 4)
--serverRun only server scripts with 10s timeout
--filter, -fFilter by type: ‘agent’, ‘agents’, or ‘workflow’
--ciCI-friendly output (no colors, proper exit codes)
--quiet, -qMinimal output
--fail-fast, -xStop on first failure
--include-testsInclude test files (test_*.py, *_test.py)
--no-reportSkip report generation
--report-dirCustom 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: 
# 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: 
# 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: 
# 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: 
# 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: 
# 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: 
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: 
# 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: 
# 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
DirectiveDescription
skip=trueSkip this script
timeout=NCustom timeout in seconds
require_env=KEY1,KEY2Required environment variables
xfail=reasonExpected 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

# 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

# GitHub Actions / GitLab CI
praisonai batch --ci --fail-fast --timeout 30

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

​
Development Workflow

# 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

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