PraisonAIUI/docs/getting-started/cli.md

CLI Reference

Complete reference for the aiui command-line interface.

Core Commands

aiui run

The primary command — run an AI server with your app.py or chat.yaml.

aiui run <FILE> [OPTIONS]

Option	Description	Default
FILE	Python file (app.py) or YAML config (chat.yaml)	required
--port, -p	Server port	8000
--host	Bind address	127.0.0.1
--reload	Auto-reload on file changes	false
--style, -s	UI style: chat, dashboard, agents, playground, docs, custom	chat
--backend	AI backend: praisonai, default	default
--workers	Number of workers	1
--ssl-certfile	SSL certificate for HTTPS	—
--ssl-keyfile	SSL private key for HTTPS	—

Examples:

aiui run app.py                          # Chat mode on port 8000
aiui run app.py --style dashboard        # Dashboard mode
aiui run app.py --port 3000 --reload     # Custom port with hot-reload
aiui run chat.yaml                       # YAML-defined chat agent
aiui run app.py --backend praisonai      # Use PraisonAI WebSocketGateway

---

aiui init

Initialize a new PraisonAIUI project.

aiui init [OPTIONS]

Option	Description	Default
--template, -t	Template: minimal, docs, marketing	minimal
--force, -f	Overwrite existing files	false
--frontend	Scaffold full Vite + React + shadcn project	false

Examples:

aiui init                        # Minimal project
aiui init --template docs        # Documentation site template
aiui init --frontend             # Full React frontend scaffold

---

aiui validate

Validate your configuration file.

aiui validate [OPTIONS]

Option	Description	Default
--config, -c	Path to config file	aiui.template.yaml
--strict	Enable strict validation	false

---

aiui build

Build manifests from configuration (for docs/static site mode).

aiui build [OPTIONS]

Option	Description	Default
--config, -c	Path to config file	aiui.template.yaml
--output, -o	Output directory	aiui
--minify	Minify JSON output	false

---

aiui serve

Serve the built site locally with a production-ready HTTP server.

aiui serve [OPTIONS]

Option	Description	Default
--config, -c	Path to config file	aiui.template.yaml
--port, -p	Server port	8000
--host	Bind address	127.0.0.1
--reload	Watch for changes and rebuild	false
--style, -s	UI style override	auto-detected
--ssl-certfile	SSL certificate for HTTPS	—
--ssl-keyfile	SSL private key for HTTPS	—

---

aiui dev

Development dashboard — switch between examples live.

aiui dev [OPTIONS]

Option	Description	Default
--examples, -e	Directory containing example projects	examples
--port, -p	Port for dev server	9000

---

aiui doctor

Run structured diagnostics against a running AIUI server.

aiui doctor [OPTIONS]

Option	Description	Default
--server, -s	Server URL to diagnose	http://127.0.0.1:8000
--json	Output results as JSON	false

Checks: health, provider, gateway, features, config, datastore, channels.

---

aiui test

Run integration tests against a running server.

aiui test <SUITE>

Suite	Description
chat	Chat WebSocket send/receive
memory	Memory CRUD operations
sessions	Session management
endpoints	API endpoint availability
all	Run all test suites

---

Management Commands

All management commands connect to a running server (default http://127.0.0.1:8000). Use --server URL to target a different server.

aiui sessions

aiui sessions list                          # List all sessions
aiui sessions create                        # Create new session
aiui sessions get <SESSION_ID>              # Get session details
aiui sessions delete <SESSION_ID>           # Delete session
aiui sessions messages <SESSION_ID>         # Get message history

aiui memory

aiui memory list [--type short|long|entity|all]   # List memories
aiui memory add "Remember this" [--type long]     # Add memory
aiui memory search "query" [--limit 10]           # Search memories
aiui memory clear [--type all]                    # Clear memories
aiui memory status                                # Memory backend status
aiui memory context "query" [--limit 5]           # Get context for prompt

aiui skills

aiui skills list        # List all skills
aiui skills status      # Show skills status
aiui skills discover    # Discover available skills

aiui provider

aiui provider status    # Show active provider info
aiui provider health    # Check provider health
aiui provider agents    # List agents from provider

aiui config

aiui config get [KEY]            # Get config (empty = show all)
aiui config set KEY VALUE        # Set a config value
aiui config list                 # List all config keys
aiui config history [--limit 20] # Show change history

aiui schedule

aiui schedule list                                     # List scheduled jobs
aiui schedule add "job-name" "message" [--every 60]    # Add job (seconds)
aiui schedule remove <JOB_ID>                          # Remove job
aiui schedule status                                   # Scheduler status

aiui approval

aiui approval list [--status pending|resolved|all]     # List approvals
aiui approval pending                                  # Pending count
aiui approval resolve <ID> [--approved|--denied] [--reason "..."]

aiui workflows

aiui workflows list                # List workflows
aiui workflows run <WORKFLOW_ID>   # Run a workflow
aiui workflows status              # Workflow status
aiui workflows runs                # Run history

aiui hooks

aiui hooks list                    # List all hooks
aiui hooks trigger <HOOK_ID>       # Trigger a hook
aiui hooks log [--limit 20]        # Hook execution log

aiui eval

aiui eval status                                         # Eval status
aiui eval list [--limit 20] [--agent-id ID]              # List evaluations
aiui eval scores                                         # Scores by agent
aiui eval judges                                         # List judges
aiui eval run --input "..." --output "..." [--expected "..."]  # Run eval

aiui traces

aiui traces status                              # Tracing status
aiui traces list [--limit 20]                   # List traces
aiui traces spans [--limit 20] [--trace-id ID]  # List spans
aiui traces get <TRACE_ID>                      # Get trace details

aiui pages

aiui pages list    # List all sidebar pages (with groups, icons)
aiui pages ids     # Print page IDs (useful for set_pages() whitelist)

aiui features

aiui features list     # List all registered features
aiui features status   # Feature health summary

aiui health-check

Check server health. Can also be invoked as aiui health for convenience.

aiui health-check [--detailed]    # Check server health
aiui health [--detailed]          # Alias for health-check

aiui session-ext

Extended session operations:

aiui session-ext state <SESSION_ID>                          # Get session state
aiui session-ext save-state <SESSION_ID> --key K --value V   # Save state
aiui session-ext labels <SESSION_ID>                         # Get labels
aiui session-ext usage <SESSION_ID>                          # Usage stats
aiui session-ext compact <SESSION_ID>                        # Compact context
aiui session-ext reset <SESSION_ID>                          # Reset state

---

Exit Codes

Code	Meaning
0	Success
1	Configuration error
2	File not found
3	Build error

Environment Variables

Variable	Description	Default
OPENAI_API_KEY	OpenAI API key	—
PRAISONAI_MODEL	Default model	gpt-4o-mini
AIUI_DATA_DIR	Data directory	~/.praisonaiui
AIUI_CONFIG	Config file path	aiui.template.yaml
AIUI_OUTPUT	Build output dir	aiui