Module cli 

Plugin-contributed CLI subcommands — the M7 Plugin::commands() deferral landing.

Plugins implement PluginCommand to expose a clap subcommand and an async handler. App::build() retains every registered plugin in topological order; dispatch walks that list, collects each plugin’s commands, builds a single top-level clap parser, and routes the user’s args to the right handler.

Why a trait, not a function pointer

Plugin commands are async, and the implementation often needs to capture instance state from the plugin (a configured prefix, a handler registry, etc.). Box<dyn PluginCommand> lets a plugin pass values through; a fn pointer can’t carry closure state.

Why clap

clap is the de-facto Rust CLI library and is already in use by umbral-cli. Plugins return a clap::Command, which carries help text, arg validation, and subcommand groupings for free. The dispatcher composes the per-plugin Command values under a single parent so umbral-cli <plugin-cmd> works as one tree.

Example

use umbral::cli::{dispatch, CliError, PluginCommand};

struct WorkerCmd;

#[async_trait::async_trait]
impl PluginCommand for WorkerCmd {
    fn command(&self) -> clap::Command {
        clap::Command::new("tasks-worker")
            .about("Run the background task worker")
            .arg(clap::Arg::new("once")
                .long("once")
                .action(clap::ArgAction::SetTrue))
    }

    async fn run(&self, m: &clap::ArgMatches) -> Result<(), CliError> {
        if m.get_flag("once") {
            umbral_tasks::run_worker_once().await?;
        } else {
            // run_worker loops forever
            umbral_tasks::run_worker(Default::default()).await
        }
        Ok(())
    }
}

Enums

DispatchOutcome

Outcome of a dispatch call. Lets the caller decide what to do when no plugin command matched — typically the framework binary then falls through to its hardcoded subcommands (serve, migrate, makemigrations, …).

Traits

PluginCommand

One CLI subcommand contributed by a plugin.

Functions

command_catalog

Collect every plugin-contributed command as (name, about) pairs.

dispatch

Dispatch CLI args across the registered plugins’ commands.

render_help

Render the unified command listing shown on help / unknown-command.

Type Aliases

CliError

Error returned by a plugin command. Boxed so plugins can return any concrete error type without forcing the trait into a generic-over-E shape.