CLI Reference - PraisonAI

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

How CLI Dispatch Works

PraisonAI uses a unified CLI entry point with Typer as the primary dispatcher: A bare prompt routes to Typer run — the same modern engine as praisonai run "…". Flags accepted by run itself (--model, --continue, --session, --output, --stream, --verbose, …) are forwarded to the modern engine too. Only YAML files and legacy-only flags (--framework, --auto, --serve, …) reach the legacy shim; when a legacy-only flag forces that fallback, a one-line stderr notice points at the modern equivalent.

As of PraisonAI 4.x (PR #3466), a bare prompt combined with a flag run accepts — --model, --continue, --session, --output, --stream, --verbose, … — now reaches the modern engine (session continuity, --output modes, credential gate, permissions all in effect).

When no credentials are configured, both praisonai (bare) and praisonai run check before doing any agent work. In a TTY, the user is offered the setup wizard. In CI or --output json mode, the command exits 1 with a clear error on stderr. See First-run Onboarding for the full behaviour matrix.

PraisonAI now fails loud on CLI registration errors. If you see a new ImportError after upgrading, a Typer subcommand or one of its dependencies failed to import — fix the import rather than ignoring the error.

Unknown Command Guard (legacy path)

The guard fires on the legacy dispatcher only; a plain praisonai show now reaches Typer run and is sent to the model as the literal prompt show. It only kicks in once an invocation is already on the legacy path — because it carries a flag or points at a .yaml/.yml file — and a lone token there looks like a mistyped or reserved command.

What Triggers It

The guard runs only when the invocation already reached legacy (a flag or a .yaml/.yml file) and the lone token looks like a mistyped or reserved command. A bare praisonai show skips legacy entirely and routes to Typer run.

Command	Route	Result
`praisonai show` (bare)	Typer `run`	prompt `show` sent to the model
`praisonai show --framework crewai`	Legacy	`Unknown command: 'show'` hint + `exit 2`
`praisonai memoyr --framework crewai`	Legacy	`Did you mean: memory?` + `exit 2`
`praisonai "write a poem"` (bare)	Typer `run`	prompt sent to the model

The Two Hint Shapes

On the legacy path, a reserved verb prints its canonical replacements:

$ praisonai show --framework crewai
Unknown command: 'show'
There is no top-level 'show' command. Did you mean one of:
  praisonai paths           # storage paths
  praisonai version show    # version details
  praisonai memory show     # memory contents
  praisonai config show     # configuration
$ echo $?
2

A typo of a known command prints a Did you mean: suggestion via difflib (cutoff 0.8):

$ praisonai memoyr --framework crewai
Unknown command: 'memoyr'
Did you mean: memory?
Run 'praisonai --help' to see available commands, or use 'praisonai run "<prompt>"' to send a prompt to the model.
$ echo $?
2

On the legacy path the guard is case-insensitive — praisonai SHOW --framework crewai fires the same reserved-verb hint as its lowercase form.

Exit Codes & Output Stream

Outcome	Exit code	Stream
Guard hit on legacy (reserved verb or typo)	`2`	Hint on `stderr`
Normal prompt or command	`0`	Result on `stdout`

The hint goes to stderr so it can be redirected separately in scripts, and the check runs before any LLM client is initialised — cost is $0.

Quick Start

Direct Prompt Execution

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

A bare prompt is identical to praisonai run "hello world" — same modern engine, same features (session continuity, --output modes, credential gate, permissions/checkpoints).

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 - uses praisonai framework by default
praisonai agents.yaml

# Interactive mode with slash commands
praisonai chat

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

CLI Help Panels

--help grouped into 7 stable, categorised panels

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

Usage

Local token/cost spend reporting across sessions

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

Tracker

Step-by-step execution tracking with quality judging

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). Defaults to `praisonai` when neither CLI flag nor YAML `framework:` is set.	`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

Tool Approval & Safety

Flag	Description	Example
`--safe / --no-safe`	Safe mode (default ON): require approval for file writes and commands	`praisonai code "..." --no-safe`
`--dangerously-skip-approval`	Skip every approval prompt and run dangerous tools unguarded	`praisonai code "..." --dangerously-skip-approval`
`--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`
`--approval <backend>`	Route approvals to a backend (`console`, `slack`, …)	`praisonai "task" --approval slack`
`--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`	Comma-separated tool names or a path to a `tools.py` file. Names are resolved through the unified ToolResolver.	`praisonai "task" --tools tavily_search,github`
`--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`

--tools accepts either a comma-separated list of tool names or a tools.py file path. Names go through the same ToolResolver chain as YAML and Python, so a name unknown to every source prints Warning: Unknown tool '<name>' and is skipped. Loading a local tools.py file still requires PRAISONAI_ALLOW_LOCAL_TOOLS=true. Run praisonai tools list to see resolvable names.

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 — file path OR comma-separated tool names	`praisonai "task" --query-rewrite --rewrite-tools "internet_search,duckduckgo_search"`

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 — file path OR comma-separated tool names	`praisonai "task" --expand-prompt --expand-tools "internet_search,duckduckgo_search"`
`--include-rules`	Include rules file	`praisonai "task" --include-rules rules.md`
`--no-rules`	Disable auto-loading of project instruction files	`praisonai "task" --no-rules`
`--no-context`	Disable AGENTS.md/CLAUDE.md auto-loading into system prompt for `chat`, `run`, `code`, and `tui`	`praisonai chat --no-context`
`--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`

Note: As of PR #1713, --deploy --schedule invokes the real DeployHandler (previously a stub). Combine with --provider {gcp,aws,azure} and --max-retries N. See Scheduler Deployment for details.

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`	Terminal-native interactive chat REPL	`praisonai chat`
`knowledge`	Manage knowledge base	`praisonai knowledge add doc.pdf`
`session`	Manage sessions	`praisonai session list`
`usage`	Local token/cost spend reporting	`praisonai usage --by model`
`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`
`tracker`	Autonomous agent tracking	`praisonai tracker run "task"`

UI Commands (Browser-Based)

Command	Description	Example
`ui`	Start default web UI (Chainlit)	`praisonai ui`
`ui chat`	Browser-based chat UI	`praisonai ui chat`
`ui code`	Browser-based code assistant UI	`praisonai ui code`
`ui realtime`	Browser-based realtime/voice UI	`praisonai ui realtime`
`ui gradio`	Gradio-based web UI	`praisonai ui gradio`

All browser-based UIs are under the ui namespace. Terminal commands (chat, code, tui) never open a browser.

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 Profiling

Flag	Description	Example
`--profile`	Enable CLI profiling (timing breakdown)	`praisonai chat "task" --profile`
`--profile-deep`	Enable deep profiling (cProfile stats, higher overhead)	`praisonai chat "task" --profile --profile-deep`

Profiling is only supported for terminal-native execution commands:

praisonai chat "prompt" --profile
praisonai code "prompt" --profile
praisonai run agents.yaml --profile

Profiling is NOT supported for browser-based UI commands (praisonai ui ...), TUI (praisonai tui), or long-running servers.

Example Output:

praisonai chat --profile "What is 2+2?"

four

╭───────────────────────────────── Profiling ──────────────────────────────────╮
│  Import           587.0ms                                                    │
│  Agent setup        0.1ms                                                    │
│  Execution       2697.5ms                                                    │
│  ────────────  ──────────                                                    │
│  Total           3284.6ms                                                    │
╰──────────────────────────────────────────────────────────────────────────────╯

​Installation

​How CLI Dispatch Works

​Unknown Command Guard (legacy path)

​What Triggers It

​The Two Hint Shapes

​Exit Codes & Output Stream

​Quick Start

​Direct Prompt Execution

​With Specific Model

​Verbose Mode

​Basic Math Calculation

​Other Examples

​Default Tools

​Tool Call Tracking

​New CLI Features

CLI Help Panels

Tool Tracking

Tool Approval

Slash Commands

Autonomy Modes

Cost Tracking

Usage

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

Tracker

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

​UI Commands (Browser-Based)

​Skills Commands

Installation

How CLI Dispatch Works

Unknown Command Guard (legacy path)

What Triggers It

The Two Hint Shapes

Exit Codes & Output Stream

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

UI Commands (Browser-Based)

Skills Commands

Global Options

Combining Features

CLI Profiling