Skip to main content
from praisonaiagents import Agent

agent = Agent(name="dispatcher", instructions="Dispatch CLI commands to the right handler.")
agent.start("Run the deploy command with the staging environment.")
The user types praisonai …; the dispatcher routes to Typer subcommands, version flags, or the legacy prompt path. PraisonAI picks one of five paths based on what you type — and adding a new subcommand means it Just Works.

​
Dispatch Paths

​
Quick Start

1

Check Version

praisonai --version
# Fast path - no heavy imports
2

Interactive Mode

praisonai
# Drops into Typer's interactive TUI
3

Get Help

praisonai --help
# Auto-generated help with all subcommands
4

Use Subcommands

praisonai chat "Build a weather agent"
# Routes to Typer automatically
5

Free-text Prompts

praisonai "Build a weather agent"
# Routes to legacy for direct prompts

​
How It Works

ComponentPurposeRoute Decision
main()Entry routerApplies 5 rules in order
_find_first_command()Positional finderSkips flags, finds command
_get_typer_commands()Auto-discoveryCached command introspection
TyperSubcommand handlerRegistered commands only
LegacyFallback handlerEverything else

​
Routing Rules

#What you typeRouteNotes
1praisonai --version / praisonai -VVersion short-circuitPrints version and returns. Does not import praisonai.cli.* — stays fast even with broken optional deps. Pinned by TestVersionShortCircuit.
2praisonai --help / praisonai -hTyperTyper’s auto-generated help lists every registered subcommand (auto-discovered, no manual list).
3praisonai (no argv)TyperDrops into Typer’s interactive TUI.
4praisonai --verbose / praisonai -o json (only flags)Typer_find_first_command returns None → Typer handles global-flag-only cases.
5praisonai chat ... (first positional ∈ registered commands)TyperAuto-discovered via Click introspection of app. Adding a new subcommand to cli/app.py makes it routable here with zero dispatcher changes.
6praisonai "Build a weather agent" (free-text — token contains a space)Legacy → direct promptMulti-word prompts skip the guard and run as a one-shot prompt.
7praisonai agents.yaml (filename, not a registered command)Legacy → direct promptRouting decision is by command-set membership, NOT by os.path.isfile(). A typo’d YAML path also routes to legacy and surfaces there.
8praisonai hello (single word, not a typo of any command)Legacy → direct promptAn unrecognised single word still runs as a prompt (backward-compatible).
9praisonai show (reserved verb)Guard → stderr hint, exit 2classify_unknown_command catches reserved verbs and prints a suggestions list instead of a paid LLM call.
10praisonai memoyr (single-word typo of memory)Guard → stderr hint, exit 2difflib.get_close_matches(cutoff=0.8) matches the typo and prints Did you mean: memory?.

​
Auto-Discovery

Commands registered in praisonai/cli/app.py become routable automatically through Click introspection.
Adding a new subcommand? Register it in praisonai/cli/app.py (e.g. app.add_typer(my_app, name="mycmd")) and the dispatcher picks it up automatically — praisonai mycmd ... routes to Typer with no changes to __main__.py. The command set is discovered once via click.Context.list_commands() and cached behind a thread-safe lock.
# In praisonai/cli/app.py
from .commands.mycmd import app as mycmd_app

def register_commands():
    # ... other commands ...
    app.add_typer(mycmd_app, name="mycmd", help="My new command")
    # That's it - no dispatcher changes needed
The auto-discovery cache (_get_typer_commands()) works by:
  1. Importing the Typer app and calling register_commands()
  2. Using Click’s introspection to list all registered commands
  3. Caching the result in _typer_commands_cache with thread safety
  4. Returning an empty set on failure (cache not poisoned for retry)

​
Common Patterns

​
Bare Prompt

praisonai "Create a Python script that scrapes weather data"
# Routes to legacy - spaces in token indicate free-text prompt

​
YAML File

praisonai agents.yaml
# Routes to legacy - filename not in registered command set

​
Subcommand with Global Flags

praisonai --verbose chat "Hello world"
# --verbose is skipped when finding first positional (chat)
# Routes to Typer since 'chat' is a registered command

​
Unknown-command guard

The dispatcher intercepts single-word command-like tokens so a mistyped verb never becomes a paid LLM call. classify_unknown_command in praisonai/cli/legacy/dispatch/argparse_builder.py returns a hint string only when a lone token looks like a mistyped or reserved command; otherwise it returns None and the token runs as a prompt.
Input tokenClassificationResult
"" / NoneNot guardedRuns as prompt
"write a poem" (contains a space)Not guardedRuns as prompt
show (reserved verb, case-insensitive)GuardedUnknown command: 'show' + suggestions
memoyr (close typo of memory, cutoff 0.8)GuardedUnknown command: 'memoyr' + Did you mean: memory?
hello (single word, no match)Not guardedRuns as prompt

​
When it fires

You typeGuard fires?What happens
praisonai show✅ reserved verbstderr hint listing paths / version show / memory show / config show, exit 2
praisonai memoyr✅ close typo (cutoff 0.8)stderr Did you mean: memory? + praisonai run "<prompt>" hint, exit 2
praisonai hello❌ single word, unmatchedrouted as a direct prompt
praisonai "write a poem"❌ multi-wordrouted as a direct prompt
praisonai run "show"❌ argument to run, not a top-level tokenLLM sees "show" as a prompt
The hint prints to stderr with exit code 2. Shell scripts must not swallow stderr if they need the diagnostic.
To send a single word to the model, wrap it in praisonai run "<word>" — arguments to run bypass the guard by construction.

​
Best Practices

The --version flag takes a fast path that prints version information without importing any praisonai.cli.* modules. This keeps the command responsive even if optional dependencies are broken or missing. The version check happens before any heavy imports or command discovery.
To add a new subcommand, simply register it in praisonai/cli/app.py using app.add_typer(). The dispatcher automatically discovers it through Click introspection with no manual updates needed to routing logic. The command becomes available immediately after registration.
Multi-word bare positionals (e.g. praisonai "build a weather agent") still fall through to legacy and run as a direct prompt. Single-word tokens go through classify_unknown_command first: a reserved verb like show or a close typo like memoyr fails fast with a hint on stderr and exits with code 2, while an unrecognised single word (e.g. hello) still runs as a prompt for backward compatibility. Use praisonai run "hello" to send a genuine single-word prompt.
Registration errors from register_commands() propagate directly to the user — the dispatcher does not swallow them. If an optional dependency is missing or a command fails to register, you see the real error instead of silent fallback behavior. This fail-loud approach aids debugging.
Registration errors fail loud. If register_commands() raises (e.g. an ImportError from a missing optional dep), the exception propagates from praisonai ... — you see the real error, not Typer’s “no command” page. This is intentional and pinned by tests.

CLI Reference

Complete command reference

CLI Commands

Basic CLI usage guide

Gateway

Multi-bot WebSocket gateway

Version

Version management