Command Line Interface
Use PraisonAI directly from your terminal with simple commands
from praisonaiagents import Agent
agent = Agent(name="cli-assistant", instructions="Help users with CLI commands.")
agent.start("List all available praisonai CLI commands.")The user runs a praisonai command in the terminal; the CLI loads config and drives the agent to completion.
How It Works
PraisonAI CLI provides a simple way to interact with AI agents directly from your terminal. You can run quick commands, specify LLM options, or use YAML configuration files for more complex scenarios.
Quick Start
- Install Package
Install the PraisonAI package:
bash pip install praisonai - Set API Key
Set your OpenAI API key as an environment variable:
bash export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
Usage Examples
Simple Command
Run a simple command directly:
praisonai "write a movie script in 3 lines"With LLM Option
Specify a different LLM model:
praisonai "write a movie script in 3 lines" --llm gpt-4o-miniUsing YAML Config
Run agents defined in a YAML file:
praisonai agents.yamlConfiguration
Create Config
Initialize a new agents.yaml file for your project:
praisonai --init "Create a movie script about AI"This will create an agents.yaml file with predefined configuration for your task.
Auto Mode
Let PraisonAI automatically create and configure agents:
praisonai --auto "Create a movie script about AI"This mode will analyze your task and set up appropriate agents automatically.
Features
Run AI tasks directly from your terminal with simple commands.
LLM OptionsChoose from different LLM models for your specific needs.
YAML SupportUse YAML files for complex agent configurations and workflows.
Auto ConfigurationAutomatic agent setup based on task requirements.
Model CatalogueDiscover, describe, and validate LLM models from the CLI.
Validate CLI
Validate YAML configuration files before running:
# Validate a single file
praisonai validate agents.yaml
# Validate all YAML files in a directory
praisonai validate check . --strict
# Print the full configuration schema
praisonai validate schema
# JSON output for CI
praisonai validate agents.yaml --json| Subcommand | Purpose |
|---|---|
validate <file> | Validate a single YAML config |
validate check [dir] | Scan a directory for YAML errors |
validate schema | Print schema fields, types, and required markers |
See the Validate CLI reference for all flags and output formats.
Discovering Models
Browse the full model catalogue, inspect capabilities and costs, or validate a model ID before running an agent:
# List all available models
praisonai models list
# Filter by provider
praisonai models list --provider openai
# Inspect a specific model
praisonai models describe gpt-4o
# Validate a model ID (shows suggestions on typos)
praisonai models validate gpt-4o-mniFull reference for praisonai models list, describe, and validate
Workflow CLI
Manage and execute YAML workflows directly from the command line:
# Run a YAML workflow
praisonai workflow run research.yaml
# Run with variables
praisonai workflow run research.yaml --var topic="AI trends"
# Validate a workflow
praisonai workflow validate research.yaml
# Create from template (simple, routing, parallel, loop)
praisonai workflow template routing --output my_workflow.yaml
# Auto-generate a workflow from topic
praisonai workflow auto "Research AI trends" --pattern parallel
# List available workflows
praisonai workflow list
# Show help
praisonai workflow helpWorkflow CLI Options
| Flag | Description |
|---|---|
--var key=value | Set variable for YAML workflows |
--pattern <pattern> | Pattern for auto-generation (sequential, parallel, routing, loop) |
--output <file> | Output file for templates/auto-generation |
--planning | Enable planning mode |
--reasoning | Enable reasoning mode |
--verbose | Enable verbose output |
--save | Save output to file |
What workflow validate Guarantees
praisonai workflow validate <file.yaml> checks a workflow against the schema and cross-references every agent reference. It now guarantees:
- Every workflow under
examples/yaml/workflows/passes (enforced by a regression test). - Agent-existence checks traverse nested
route:,parallel:,loop:,repeat:, andif:payloads — an undefined agent in any of them is flagged with a clear error and non-zero exit. loop: {over: <variable_name>}is treated as a variable, not an agent reference, so it is never flagged.
Sample output — pass:
$ praisonai workflow validate research.yaml
✓ research.yaml is validSample output — undefined agent:
$ praisonai workflow validate broken.yaml
✗ broken.yaml is invalid
Step 'route' references undefined agent 'reviewer'Next Steps
Learn about YAML workflow configuration and patterns
Workflow PatternsExplore routing, parallel, loop, and repeat patterns
API ReferenceView the complete API documentation
Best Practices
Validate YAML before running
Catch schema errors early with praisonai validate agents.yaml (or praisonai validate check . --strict for a whole directory) before executing a workflow. In CI, add --json for machine-readable output so a broken config fails the pipeline instead of the agent run.
Pin the model per command
A bare praisonai "..." uses the default provider. Pass --llm to make each invocation reproducible and cost-predictable:
praisonai "write a movie script in 3 lines" --llm gpt-4o-miniConfirm an ID exists first with praisonai models validate gpt-4o-mini to avoid silent typos.
Start with –init, graduate to YAML
Use praisonai --init "task" to scaffold an agents.yaml, then edit and re-run with praisonai agents.yaml. This keeps one-off prompts fast while giving repeatable, version-controlled configs for anything you run more than once.
Use –var to keep workflows reusable
Parameterise workflow YAML instead of hard-coding values so one file serves many runs:
praisonai workflow run research.yaml --var topic="AI trends"