CLI Reference - PraisonAI Documentation

The PraisonAI CLI provides powerful commands and flags to interact with AI agents directly from your terminal.

Installation

pip install praisonai
export OPENAI_API_KEY=your_api_key

Quick Start

Direct Prompt Execution

# Basic usage - includes 5 built-in tools by default
praisonai "hello world"

With Specific Model

# With a specific model
praisonai "list files" --llm gpt-4o-mini

Verbose Mode

# Verbose mode - shows full agent panels and tool call details
praisonai "explain AI" -v

Basic Math Calculation

# Simple calculation
praisonai "What is 2+2?"

Other Examples

# Run agents from YAML
praisonai agents.yaml

# Interactive mode with slash commands
praisonai --interactive

Default Tools

The CLI now includes 5 built-in tools by default, giving agents the ability to interact with your filesystem and the web:

Tool	Description
`read_file`	Read contents of files
`write_file`	Write content to files
`list_files`	List directory contents
`execute_command`	Run shell commands
`internet_search`	Search the web

# Example: Agent uses list_files tool automatically
praisonai "List all Python files in this directory"
# Output: Tools used: list_files
# [file listing...]

# Example: Agent uses multiple tools
praisonai "Read README.md and summarize it"
# Output: Tools used: list_files, read_file
# [summary...]

Tool Call Tracking

When tools are used, the CLI displays which tools were called:

# Non-verbose mode (default) - clean output with tool summary
praisonai "List files here"
# Output:
# Tools used: list_files
# [results...]

# Verbose mode - full panels with tool call details
praisonai "List files here" -v
# Output:
# ╭─ Agent Info ─────────────────────────────────────────────────────╮
# │  👤 Agent: DirectAgent                                           │
# │  Tools: read_file, write_file, list_files, execute_command, ...  │
# ╰──────────────────────────────────────────────────────────────────╯
# ╭───────── Tool Call ──────────╮
# │ Calling function: list_files │
# ╰──────────────────────────────╯
# [results...]

New CLI Features

Tool Tracking

Real-time tool call tracking and display

Tool Approval

Control tool execution approval with —trust and —approve-level

Slash Commands

Interactive /help, /cost, /model commands

Autonomy Modes

Control AI autonomy: suggest, auto_edit, full_auto

Cost Tracking

Real-time token usage and cost monitoring

Repository Map

Intelligent codebase mapping with tree-sitter

Interactive TUI

Rich terminal interface with completions

Message Queue

Queue messages while agent is processing

Git Integration

Auto-commit with AI messages, diff viewing

Sandbox Execution

Secure isolated command execution

All CLI Features

Deep Research

Automated multi-step research with citations

Planning

Step-by-step task execution with planning

Memory

Persistent agent memory management

Rules

Auto-discovered instructions from .praisonai files

Workflow

Multi-step YAML workflow execution

Hooks

Event-driven actions and callbacks

Claude Memory

Anthropic’s memory tool integration

Guardrail

Validate agent outputs with LLM-based guardrails

Metrics

Track token usage and cost metrics

Image Processing

Process images with vision-based AI agents

Telemetry

Enable usage monitoring and analytics

MCP

Integrate Model Context Protocol servers

Fast Context

Search codebase for relevant context

Knowledge

Manage RAG/vector store knowledge bases

Scheduler

Run agents 24/7 with timeout and cost limits

Session

Manage conversation sessions

Tools

Discover and manage available tools

Handoff

Enable agent-to-agent task delegation

Auto Memory

Automatic memory extraction and storage

Todo

Manage todo lists from tasks

Router

Smart model selection based on task complexity

Flow Display

Visual workflow tracking

Query Rewrite

RAG query optimization

Prompt Expansion

Expand prompts with detailed context

Prompt Caching

Cache prompts for cost reduction

Web Search

Real-time web search integration

Web Fetch

Fetch and process URL content

Docs

Manage project documentation

Mentions

Reference files and context with @mentions

AI Commit

AI-generated commit messages

Serve

Run agents as API server

n8n Integration

Import n8n workflows

Agent Skills

Manage modular skills for agents

Complete CLI Reference

Core Flags

Flag	Description	Example
`--framework`	Specify framework (crewai, autogen, praisonai)	`praisonai agents.yaml --framework crewai`
`--ui`	UI mode (chainlit, gradio)	`praisonai --ui chainlit`
`--llm`	Specify LLM model	`praisonai "task" --llm gpt-4o`
`--model`	Model name	`praisonai "task" --model gpt-4o`
`-v`, `--verbose`	Verbose output with full agent panels	`praisonai "task" -v`
`--save`, `-s`	Save output to file	`praisonai "task" --save`

Interactive Mode

Flag	Description	Example
`--interactive`, `-i`	Start interactive mode with tools	`praisonai --interactive`
`--chat`, `--chat-mode`	Single prompt in interactive style	`praisonai "task" --chat`

Tool Approval & Safety

Flag	Description	Example
`--trust`	Auto-approve all tool executions	`praisonai "task" --trust`
`--approve-level`	Auto-approve up to risk level (low/medium/high/critical)	`praisonai "task" --approve-level high`
`--autonomy`	Set autonomy mode (suggest, auto_edit, full_auto)	`praisonai "task" --autonomy auto_edit`
`--sandbox`	Enable sandbox execution (off, basic, strict)	`praisonai "task" --sandbox basic`
`--guardrail`	Validate output against criteria	`praisonai "task" --guardrail "criteria"`

Planning & Memory

Flag	Description	Example
`--planning`	Enable planning mode	`praisonai "task" --planning`
`--planning-tools`	Tools for planning phase	`praisonai "task" --planning --planning-tools tools.py`
`--planning-reasoning`	Enable chain-of-thought in planning	`praisonai "task" --planning --planning-reasoning`
`--auto-approve-plan`	Auto-approve generated plans	`praisonai "task" --planning --auto-approve-plan`
`--memory`	Enable file-based memory	`praisonai "task" --memory`
`--auto-memory`	Auto extract memories	`praisonai "task" --auto-memory`
`--claude-memory`	Enable Claude Memory Tool (Anthropic only)	`praisonai "task" --llm anthropic/claude-3 --claude-memory`
`--user-id`	User ID for memory isolation	`praisonai "task" --memory --user-id user123`
`--auto-save`	Auto-save session with name	`praisonai "task" --auto-save mysession`
`--history`	Load history from last N sessions	`praisonai "task" --history 3`

Tools & Extensions

Flag	Description	Example
`--tools`, `-t`	Load additional tools	`praisonai "task" --tools my_tools.py`
`--mcp`	Use MCP server	`praisonai "task" --mcp "npx server"`
`--mcp-env`	MCP environment variables	`praisonai "task" --mcp "cmd" --mcp-env "KEY=val"`
`--handoff`	Agent delegation (comma-separated)	`praisonai "task" --handoff "a1,a2"`
`--final-agent`	Final agent for multi-agent tasks	`praisonai "task" --final-agent summarizer`

Web & Search

Flag	Description	Example
`--web-search`	Enable native web search	`praisonai "task" --web-search`
`--web-fetch`	Enable web fetch for URLs	`praisonai "task" --web-fetch`
`--research`	Run deep research on topic	`praisonai research "topic"`
`--query-rewrite`	Rewrite query for better results	`praisonai "task" --query-rewrite`
`--rewrite-tools`	Tools for query rewriting	`praisonai "task" --query-rewrite --rewrite-tools tools.py`

Context & Prompts

Flag	Description	Example
`--fast-context`	Add code context from path	`praisonai "task" --fast-context ./src`
`--file`, `-f`	Read input from file	`praisonai "task" --file input.txt`
`--url`	Repository URL for context	`praisonai "task" --url https://github.com/repo`
`--goal`	Goal for context engineering	`praisonai --url repo --goal "understand auth"`
`--auto-analyze`	Enable automatic analysis	`praisonai --url repo --auto-analyze`
`--expand-prompt`	Expand short prompt to detailed	`praisonai "task" --expand-prompt`
`--expand-tools`	Tools for prompt expansion	`praisonai "task" --expand-prompt --expand-tools tools.py`
`--include-rules`	Include rules file	`praisonai "task" --include-rules rules.md`
`--max-tokens`	Maximum tokens for response	`praisonai "task" --max-tokens 4000`

Monitoring & Display

Flag	Description	Example
`--metrics`	Show token usage and costs	`praisonai "task" --metrics`
`--telemetry`	Enable usage monitoring	`praisonai "task" --telemetry`
`--flow-display`	Visual workflow tracking	`praisonai agents.yaml --flow-display`
`--todo`	Generate todo list from task	`praisonai "plan" --todo`
`--router`	Smart model selection	`praisonai "task" --router`
`--router-provider`	Provider for router	`praisonai "task" --router --router-provider openai`
`--image`	Process image file	`praisonai "describe" --image photo.png`
`--prompt-caching`	Enable prompt caching	`praisonai "task" --prompt-caching`

Server & Deployment

Flag	Description	Example
`--serve`	Start API server for agents	`praisonai agents.yaml --serve`
`--port`	Server port (default: 8005)	`praisonai agents.yaml --serve --port 8080`
`--host`	Server host (default: 127.0.0.1)	`praisonai agents.yaml --serve --host 0.0.0.0`
`--deploy`	Deploy the application	`praisonai agents.yaml --deploy`
`--provider`	Deployment provider (gcp, aws, azure)	`praisonai --deploy --provider aws`
`--schedule`	Schedule deployment	`praisonai --deploy --schedule daily`
`--schedule-config`	Schedule configuration	`praisonai --deploy --schedule-config config.yaml`
`--max-retries`	Max retries for deployment	`praisonai --deploy --max-retries 3`

Workflow & Integration

Flag	Description	Example
`--workflow`	Run inline workflow steps	`praisonai --workflow "step1:action1;step2:action2"`
`--workflow-var`	Workflow variables	`praisonai --workflow "..." --workflow-var "key=val"`
`--n8n`	Export workflow to n8n	`praisonai agents.yaml --n8n`
`--n8n-url`	n8n instance URL	`praisonai --n8n --n8n-url http://localhost:5678`
`--api-url`	PraisonAI API URL for n8n	`praisonai --n8n --api-url http://localhost:8005`

Initialization & Setup

Flag	Description	Example
`--auto`	Enable auto mode	`praisonai --auto "create agents for task"`
`--init`	Initialize agents with topic	`praisonai --init "research assistant"`
`--merge`	Merge with existing agents.yaml	`praisonai --auto "task" --merge`

Model Providers

Flag	Description	Example
`--hf`	Hugging Face model	`praisonai "task" --hf model-name`
`--ollama`	Ollama model	`praisonai "task" --ollama llama2`
`--dataset`	Dataset for training	`praisonai --dataset data.json`

Special Modes

Flag	Description	Example
`--realtime`	Start realtime voice interface	`praisonai --realtime`
`--call`	Start PraisonAI Call server	`praisonai --call`
`--public`	Expose server with ngrok (with —call)	`praisonai --call --public`
`--claudecode`	Enable Claude Code integration	`praisonai "task" --claudecode`

Slash Commands (Interactive Mode)

Command	Description
`/help`	Show available commands
`/exit`, `/quit`	Exit interactive mode
`/clear`	Clear the screen
`/tools`	List available tools (5 built-in)

Both direct prompts and interactive mode include 5 built-in tools by default: read_file, write_file, list_files, execute_command, internet_search. Tool usage is automatically tracked and displayed.

Standalone Commands

Command	Description	Example
`chat`	Start web-based Chainlit chat UI	`praisonai chat`
`knowledge`	Manage knowledge base	`praisonai knowledge add doc.pdf`
`session`	Manage sessions	`praisonai session list`
`tools`	Manage tools	`praisonai tools list`
`todo`	Manage todos	`praisonai todo list`
`memory`	Manage memory	`praisonai memory show`
`rules`	Manage rules	`praisonai rules list`
`workflow`	Manage workflows	`praisonai workflow list`
`hooks`	Manage hooks	`praisonai hooks list`
`research`	Deep research	`praisonai research "query"`
`skills`	Manage agent skills	`praisonai skills list`

Skills Commands

Command	Description	Example
`skills list`	List available skills	`praisonai skills list`
`skills validate`	Validate a skill directory	`praisonai skills validate --path ./my-skill`
`skills create`	Create a new skill from template	`praisonai skills create --name my-skill`
`skills prompt`	Generate prompt XML for skills	`praisonai skills prompt --dirs ./skills`

Global Options

# Verbose output
praisonai "task" -v

# Specify LLM model
praisonai "task" --llm openai/gpt-4o

# Save output to file
praisonai "task" --save

# Enable planning mode
praisonai "task" --planning

# Enable memory
praisonai "task" --memory

Combining Features

You can combine multiple CLI features for powerful workflows:

# Research with metrics and guardrails
praisonai "Analyze market trends" --metrics --guardrail "Include sources"

# Planning with router and flow display
praisonai "Complex analysis" --planning --router --flow-display

# Multi-agent with handoff and memory
praisonai "Research and write" --handoff "researcher,writer" --auto-memory

Use praisonai --help to see all available options and commands.

CLI

​Installation

​Quick Start

​Direct Prompt Execution

​With Specific Model

​Verbose Mode

​Basic Math Calculation

​Other Examples

​Default Tools

​Tool Call Tracking

​New CLI Features

Tool Tracking

Tool Approval

Slash Commands

Autonomy Modes

Cost Tracking

Repository Map

Interactive TUI

Message Queue

Git Integration

Sandbox Execution

​All CLI Features

Deep Research

Planning

Memory

Rules

Workflow

Hooks

Claude Memory

Guardrail

Metrics

Image Processing

Telemetry

MCP

Fast Context

Knowledge

Scheduler

Session

Tools

Handoff

Auto Memory

Todo

Router

Flow Display

Query Rewrite

Prompt Expansion

Prompt Caching

Web Search

Web Fetch

Docs

Mentions

AI Commit

Serve

n8n Integration

Agent Skills

​Complete CLI Reference

​Core Flags

​Interactive Mode

​Tool Approval & Safety

​Planning & Memory

​Tools & Extensions

​Web & Search

​Context & Prompts

​Monitoring & Display

​Server & Deployment

​Workflow & Integration

​Initialization & Setup

​Model Providers

​Special Modes

​Slash Commands (Interactive Mode)

​Standalone Commands

​Skills Commands

​Global Options

​Combining Features

Installation

Quick Start

Direct Prompt Execution

With Specific Model

Verbose Mode

Basic Math Calculation

Other Examples

Default Tools

Tool Call Tracking

New CLI Features

All CLI Features

Complete CLI Reference

Core Flags

Interactive Mode

Tool Approval & Safety

Planning & Memory

Tools & Extensions

Web & Search

Context & Prompts

Monitoring & Display

Server & Deployment

Workflow & Integration

Initialization & Setup

Model Providers

Special Modes

Slash Commands (Interactive Mode)

Standalone Commands

Skills Commands

Global Options

Combining Features