Struct Cli 

pub struct Cli { /* private fields */ }

Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one

A usage spec describes a CLI’s commands, flags, and arguments once, in KDL. Most commands here read one: a .usage.kdl file given with -f, a script whose #USAGE comments declare it, or - for stdin. A binary built with the Rust framework prints its own spec, so a pipeline like mycli __usage_spec__ | usage generate markdown -f - needs no file at all.

Guides and a reference for every command: https://usage.jdx.dev/cli/

Implementations

impl Cli

pub fn command() -> &'static Command<'static>

The parse tables for this CLI.

static, so reaching them costs nothing: there is no command tree to build before a parse can start.

pub fn spec() -> &'static Spec<'static>

This CLI’s spec, for emitting, documenting, or completing.

pub fn app() -> SpecView<'static>

A borrowed cold-path view for runtime identity and sparse metadata overlays.

Parsing continues to read Self::command directly; constructing this copies no command tree and performs no work on an ordinary invocation.

pub fn render_help(cmd: &Command<'_>, long: bool) -> Option<String>

Render a help page using this CLI’s process identity.

Self::spec keeps the portable name_spec / bin_spec literals. parse() already evaluates computed name / bin when it prints help; this is the same overlay for a parse_from caller that handles usage_argv::Error::Help itself.

The page is coloured on a terminal and plain anywhere else, which is what parse() prints — a CLI that dispatches help itself should not get a duller page than one that does not.

This changed in 6.11: the page used to be plain whatever it was printed to. A caller that keeps the text rather than printing it — writing it to a file, comparing it, embedding it in a document — should ask for usage_argv::help::Style::PLAIN through Self::render_help_styled. Without a source change, NO_COLOR still forces every page plain.

pub fn render_help_styled( cmd: &Command<'_>, long: bool, style: Style, ) -> Option<String>

Render a help page with an explicit colour policy.

usage_argv::help::Style::PLAIN for a snapshot, a generated document, or anywhere the escapes would be the output rather than how it looks.

pub fn render_failure<'v>( argv: &[&'v OsStr], error: &Error<'static, 'v>, ) -> String

Render a parse failure using this CLI’s process identity.

The counterpart of Self::render_help for every error that is not a help or version request. parse() uses the same overlay on stderr.

pub fn to_kdl() -> String

This CLI’s spec as KDL, which is what usage g markdown|manpage and the completion generators read.

pub fn spec_request(argv: &[&OsStr]) -> Option<String>

This CLI’s own spec, when argv asks for it.

Some for a command line whose first word is usage_argv::SPEC_REQUEST, and None for an ordinary invocation — including one that names a command of that spelling, which keeps a declaration ahead of the built-in. Takes the command line without the program name, like Self::parse_from.

Self::parse answers it and exits. An embedder that renders its own output, or wants to refuse the request, calls this instead.

pub fn embedded_outcome(argv: &[OsString]) -> Outcome<Self>

Answer the complete usage control protocol without printing or exiting.

Input excludes the program name, like Self::parse_from. Spec and completion requests become successful stdout responses; ordinary argv is parsed, with help, version, and failures represented by the same outcome.

pub fn embedded_outcome_paletted( argv: &[OsString], palette: Palette, ) -> Outcome<Self>

Self::embedded_outcome with a remapped semantic colour map.

pub fn parse_from<'v>(argv: &[&'v OsStr]) -> Result<Self, Error<'static, 'v>>

Parse a command line, excluding the program name.

pub fn parse_from_with_warnings<'v>( argv: &[&'v OsStr], warnings: &mut Vec<Warning<'static>>, ) -> Result<Self, Error<'static, 'v>>

Parse a command line, and collect what it used that is deprecated.

Reported rather than printed: a library cannot decide where this program’s output goes, and a CLI that queues its diagnostics until its logging is up needs them as values rather than as lines on stderr. Self::parse, which is the process, renders them itself.

A warning whose deprecated_warn_at this CLI’s version has not reached is not collected — that is what declaring one means.

pub fn parse_from_argv<'v>( argv: &[&'v OsStr], ) -> Result<Self, Error<'static, 'v>>

Parse a full argv, including the program name.

This is the test- and embedding-friendly counterpart to Self::parse: it strips argv0 for an ordinary CLI and applies the same basename-based applet selection for a multicall CLI, while returning errors instead of exiting.

pub fn parse_from_argv_with_warnings<'v>( argv: &[&'v OsStr], warnings: &mut Vec<Warning<'static>>, ) -> Result<Self, Error<'static, 'v>>

Self::parse_from_argv, collecting the deprecations it used.

pub fn try_update_from<'v>( &mut self, argv: &[&'v OsStr], ) -> Result<(), Error<'static, 'v>>

Merge a command line, excluding the program name, into this value.

The counterpart of Self::parse_from for a CLI parsed more than once: a REPL’s standing options, a daemon reconfigured while it runs. The rules are stated rather than inherited, because a parse cannot be run backwards through FromStr to seed itself from a value — what the caller already has is read from the struct instead, by the checks that need to know a field is filled.

Relationships see what is already there: required, requires_if, conflicts and the rest treat a field that already holds a value as present, so this validates the union of both inputs rather than this argv alone. Environment variables and declared defaults fill only fields still empty, so an update never clobbers a value the caller set. A collection this command line mentions is replaced whole; one it says nothing about is left alone. A subcommand word naming a different variant replaces it, discarding the old variant’s fields, since selecting a command is a routing decision rather than a value to merge.

self is left untouched when this returns an error: nothing is merged until every check has passed.

Two things a standing value cannot answer, because the bytes it was parsed from are gone: a check about what a value is — a choice list, a validate expression — is skipped for a field this argv did not supply, and a requires_if comparing against a particular value does not match one that merely stands.

pub fn try_update_from_argv<'v>( &mut self, argv: &[&'v OsStr], ) -> Result<(), Error<'static, 'v>>

Merge a full argv, including the program name, into this value.

The Self::parse_from_argv counterpart of Self::try_update_from: argv0 is stripped, a multicall applet name selects its subcommand, and a view’s program name is rewritten to the command it promotes. A view projects a struct that omits the root fields it does not carry; an update has no such struct to project into, so the words are rewritten and the omitted fields are simply ones this command line said nothing about.

pub fn update_from<'v>(&mut self, argv: &[&'v OsStr])

Self::try_update_from, answering a failure the way Self::parse does: help or a version on stdout, a message on stderr, and exit.

pub fn update_from_argv<'v>(&mut self, argv: &[&'v OsStr])

Self::try_update_from_argv, exiting on failure as Self::parse does.

pub fn try_parse_from<'v>( argv: &[&'v OsStr], ) -> Result<Self, Error<'static, 'v>>

Parse using clap’s try_parse_from argv contract.

Input includes argv0 by default. #[usage(no_binary_name)] opts into treating every supplied word as an argument.

pub fn try_parse_from_with_warnings<'v>( argv: &[&'v OsStr], warnings: &mut Vec<Warning<'static>>, ) -> Result<Self, Error<'static, 'v>>

Self::try_parse_from, collecting the deprecations it used.

pub fn completion_script(shell: Shell) -> String

This CLI’s completion script for shell, to be written to a file or sourced.

Emitted under the same attribute as the command it calls, which is what makes a script that names a command the binary does not answer a compile error instead of a silence at the prompt.

pub fn completion_script_for_alias(alias: &str, shell: Shell) -> String

Register completion under a shell alias while asking this CLI’s real binary.

pub fn completion_install_plan(shell: Shell, env: &Env) -> Result<Plan, Error>

Where this CLI’s completion script for shell goes, and what else the user must do.

Nothing is written: this is the answer a preview prints. env is normally usage_argv::install::Env::from_process(); a test describes one instead.

pub fn completion_install_plan_for_alias( alias: &str, shell: Shell, env: &Env, ) -> Result<Plan, Error>

Where an alias’s completion script would go. The preview half of install_completion_for_alias.

pub fn install_completion( shell: Shell, env: &Env, on_foreign: OnForeign, ) -> Result<Installed, Error>

Write this CLI’s completion script where env says this shell looks for it.

Creates the directories above it and nothing else: no shell rc file and no PowerShell profile is edited, so a shell that needs a line of its own reports it through Installed::plan rather than having it applied.

pub fn install_completion_for_alias( alias: &str, shell: Shell, env: &Env, on_foreign: OnForeign, ) -> Result<Installed, Error>

Install under a shell alias while still asking this CLI’s real binary for answers.

pub fn completion_script_for(view: &str, shell: Shell) -> Option<String>

A declared executable view’s completion script.

pub fn completion_request(argv: &[OsString]) -> Option<String>

The word a shell is completing, answered from this CLI’s own tables.

None when argv is an ordinary invocation. The request is recognized before the parse rather than inside it: a completion is not a command this CLI runs, and putting it in the tables would make it one — visible to the grammar, the help and the spec.

pub fn parse() -> Self

impl Cli

pub fn run(argv: &[String]) -> Result<()>