CLI Dispatcher

How praisonai routes your command — version, Typer subcommand, or legacy prompt/YAML

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.")

Just type your prompt — praisonai "…" uses the same modern engine as praisonai run "…".

The user types praisonai …; the dispatcher routes to Typer subcommands, version flags, bare prompts, or the legacy YAML/flag path.

PraisonAI picks one of nine paths based on what you type — and adding a new subcommand means it Just Works.

Dispatch Paths

graph TB
    Start[📋 praisonai argv] --> V{🔍 --version<br/>or -V?}
    V -->|Yes| Print[⚡ Print version<br/>no cli.* imports]
    V -->|No| H{🔍 --help<br/>or -h?}
    H -->|Yes| Typer1[🧰 Typer help]
    H -->|No| E{🔍 argv empty?}
    E -->|Yes| Typer2[🧰 Typer TUI]
    E -->|No| F[🔎 first non-flag positional]
    F --> K{🧠 in registered<br/>Typer commands?}
    K -->|Yes| Typer3[🧰 Typer subcommand]
    K -->|No| L{🛡 implemented<br/>legacy verb?<br/>(oracle)}
    L -->|Yes| LegHandler[🤖 Legacy handler<br/>_run_legacy]
    L -->|No| T{🛡 lone token,<br/>close typo of a command?}
    T -->|Yes| Guard[❌ No such command<br/>Did you mean … — exit 2]
    T -->|No| B{🔍 bare prompt?<br/>flags all run-supported &amp;<br/>not .yaml/.yml}
    B -->|Yes| Run[🧰 Typer run<br/>run &lt;prompt&gt;]
    B -->|No| Y{🔍 .yaml/.yml first token &amp;<br/>flags all run-supported?}
    Y -->|Yes| RunYaml[🧰 Typer run<br/>run &lt;yaml&gt;]
    Y -->|No| Legacy[🤖 Legacy<br/>YAML w/ legacy flags]

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef route fill:#10B981,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff

    class Start input
    class V,H,E,K,L,T,B,Y check
    class F input
    class Print,Typer1,Typer2,Typer3,Run,RunYaml route
    class Guard,Legacy,LegHandler agent

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"
   # Identical to: praisonai run "Build a weather agent"

How It Works

Routing Rules

main() applies nine rules in order. The first match wins.

Rule 5 fires when _is_implemented_legacy_verb(first_cmd) returns True — the first token names a verb the legacy dispatcher implements (it is in the shared LEGACY_SPECIAL_COMMANDS oracle) and is not one of the ordering-hold verbs in _LEGACY_VERB_ROUTING_EXCLUSIONS. The invocation is forwarded to _run_legacy(argv) before the bare-prompt/LLM rule, so praisonai thinking status reaches the thinking handler instead of being billed as a prompt. This closed the #4327 regression where 29 implemented verbs cost ~2.5k tokens per invocation and exited 0. Rule 6 fires when _mistyped_command_suggestions(argv, first_cmd) returns a non-empty list — a lone positional token, no whitespace or path separator, not ending in .yaml/.yml, no file of that name on disk, not itself a registered command, whose difflib.get_close_matches(..., cutoff=0.8) yields a registered command that the token does not extend. A token that a command starts with (an extension like tests for test, server for serve) is dropped so it stays a valid one-word prompt. The opposite direction — a token that is a truncation of a command (deplo for deploy, versio for version) — is now kept and surfaced as a suggestion instead of being forwarded to (and billed by) the model. Rule 7 fires when _looks_like_bare_prompt(argv, first_cmd) returns True — that is, when first_cmd is non-empty, doesn’t end with .yaml/.yml, and either no dash-prefixed token appears anywhere in argv or every flag present is one that Typer run itself accepts (--model, --continue, --session, --output, --stream, …, derived at dispatch time by introspecting run‘s Click parameters). Rule 8 fires when _looks_like_yaml_run_target(argv, first_cmd) returns True — the first positional ends in .yaml/.yml and every flag is run-supported — forwarding praisonai agents.yaml … as run agents.yaml … so the workflow runs inside the modern session/output/credential/permission envelope. A single genuinely legacy-only flag (--auto, --serve, --n8n, …) still forces legacy. The short-form -s (legacy --save) and -f (legacy --file) live in _LEGACY_COLLIDING_SHORT_OPTS and also stay on legacy, so an existing script is never silently reinterpreted. If run-option discovery fails, both predicates fall back to the original conservative any-flag→legacy rule.

Second-level split inside the legacy run branch

Once an invocation reaches the legacy dispatcher’s run branch (either because the user typed praisonai run … directly, or because a legacy-only flag forced fallback there), a second predicate decides between the async-jobs API and the modern agent runner:

• First positional is not a flag, not a reserved job verb (submit / status / result / cancel / list / stream), and either ends with .yaml/.yml (the existence check happens later, inside the runner) or names an existing file → forwarded to the modern Typer agent runner (commands/run.py run_app).
• Anything else (a reserved job verb, a free-text token that isn’t a file, an empty positional list) → forwarded to handle_run_command (async-jobs argparse parser).

The reserved-verb guard is deliberately narrow — it matches the bare token equal to a job verb, so a same-named path with a separator (./submit) still routes to the modern engine and only a stray literal submit file in cwd is overridden. This preserves the pre-existing praisonai run submit … script contract.

graph TB
    Start[📋 praisonai run FIRST-TOKEN] --> Flag{🔍 starts<br/>with -?}
    Flag -->|Yes| Jobs[🤖 Jobs API<br/>argparse]
    Flag -->|No| Verb{🔍 reserved job verb?<br/>submit/status/result/<br/>cancel/list/stream}
    Verb -->|Yes| Jobs
    Verb -->|No| File{🔍 ends in .yaml/.yml?<br/>(existence not required)<br/>or otherwise an existing file?}
    File -->|Yes| Runner[✅ Modern agent runner<br/>run_app]
    File -->|No| Jobs

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef jobs fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef runner fill:#10B981,stroke:#7C90A0,color:#fff

    class Start input
    class Flag,Verb,File check
    class Jobs jobs
    class Runner runner

Never-silent legacy fallback

When an invocation reaches the legacy engine solely because it contains a flag that run doesn’t accept, praisonai prints a one-line stderr notice pointing at the modern equivalent:

Note: 'summarise this' contains a flag not supported by the modern engine;
using the legacy engine. For session continuity, --output modes and
permissions, try: praisonai run "summarise this" ...

The notice fires whenever a legacy-only flag forced the fallback — on either a prompt or a YAML workflow. A flagless .yaml/.yml reaches the modern engine and does not produce a notice.

Mistyped-verb guard

A lone token that is a close typo of a registered command exits 2 instead of being billed to an LLM.

$ praisonai deploi
Error: No such command 'deploi'.
Did you mean: deploy?
To run it as a prompt instead: praisonai run "deploi"
$ echo $?
2

The guard is deliberately narrow — it fires only when a single positional token has no whitespace, no / or path separator, does not end in .yaml/.yml, names no file on disk, is not itself a command, and difflib.get_close_matches(..., cutoff=0.8) returns a registered command that the token does not extend. Extensions (tests for test, server for serve) are dropped so legitimate one-word prompts still run; truncations (deplo, versio) are kept and suggested.

Global flags

Global flags (--output-format, --json, --quiet, …) are declared on the root Typer callback, not on run. When a bare prompt or YAML target follows one, the dispatcher hoists the global flag ahead of the synthesised run.

Click accepts a group-level option only before the subcommand, so --output-format json must be emitted as praisonai --output-format json run <target>; appended after run, Click rejects it with “No such option”.

praisonai --output-format json version   # → --output-format json version (Typer)
praisonai --output-format json hello     # → --output-format json run hello
praisonai --output-format json agents.yaml  # → --output-format json run agents.yaml

Global-only flags (hoisted ahead of run) — declared on the root callback and not on run:

Shared flags that are NOT hoisted — declared by both the root callback and run, so they stay with run and keep their existing meaning:

Behaviour Matrix

Auto-Discovery

Commands registered in praisonai/cli/app.py become routable automatically through Click introspection.

# 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 Typer run - no flags, not a .yaml/.yml file

YAML File

praisonai agents.yaml
# Routes to Typer run - same modern engine as `praisonai run agents.yaml`.
# Add run flags too: praisonai agents.yaml --continue --output json

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

Bare Prompt With run Flags

praisonai "fix the auth bug" --model gpt-4o
praisonai "summarise this" --continue
praisonai "diagnose" --output json

# All three reach the modern engine — same as praisonai run "..." <flag>.
# Session continuity, --output modes, credential gate, permissions are all in effect.

Two typo guards

There are now two guards, and they fire on different paths.

When it fires

Best Practices

Related