API Reference

xclif

class xclif.Arg(description=None, name=None)

Bases: object

Annotation metadata for positional arguments.

Use inside Annotated to attach a description or display name:

def copy(src: Annotated[str, Arg(description="Source file", name="SRC")]) -> None: ...

Parameters:

• description (str | None)

• name (str | None)

class xclif.Cascade

Bases: object

Annotation metadata to cascade an option to subcommands.

Use as a type wrapper to make an option’s value available to all subcommands via get_context():

def root(
    base_url: Cascade[WithConfig[str]] = DEFAULT_BASE_URL,
) -> None: ...

Subcommands can then use get_context()["base_url"].

class xclif.Cli(root_command, version=None, env_prefix=None, config_name=None, local_config=None, config_command=True, mcp_command=True, show_no_description=None)

Bases: object

Entry point for an Xclif-powered CLI application.

Typically constructed via from_routes() (file-based routing) or from_manifest() (pre-compiled manifest for fast startup). Direct construction is only needed when using the flat decorator API.

Parameters:

• root_command (xclif.command.Command) – The root Command of the CLI tree.

• version (str | None) – Version string shown by --version. Auto-detected from package metadata when None.

• env_prefix (str | None) – Prefix for environment-variable overrides (e.g. "MYAPP" → MYAPP_FOO). Defaults to the uppercased root command name.

• config_name (str | None) – App name used to locate the config directory via platformdirs. Defaults to the root command name.

• local_config (str | None) – Filename to look for in the current working directory as a local config file (e.g. ".myapp.toml"). When set, the file is loaded and its values take priority over the user-level config but are still overridden by env vars and CLI flags. Supports .toml and .json extensions. None (the default) disables local config.

• config_command (bool) – Whether to auto-inject the config subcommand when any parameter uses WithConfig. True (the default) keeps the current behaviour; set to False to suppress it.

• mcp_command (bool) – Whether to auto-inject the mcp subcommand when the optional mcp package is installed. True (the default) keeps the current behaviour; set to False to suppress it.

• show_no_description (bool | None) – Default value for show_no_description on all commands in the tree. When False, suppress the “No description” placeholder in help output for commands without a docstring. When None (the default), each command uses its own setting (True by default for backward compatibility). Per-command @command(show_no_description=...) overrides this default.

serve_mcp()

Start an MCP stdio server exposing all leaf commands as tools.

Requires the optional ‘mcp’ package: pip install xclif[mcp]

Return type:

None

add_command(path, command)

Mount command at the given path within the command tree.

path is a list of names from the root downward, e.g. ["server", "start"] mounts command as myapp server start. Intermediate groups are created automatically if they don’t exist.

Parameters:

• path (list[str])

• command (Command)

Return type:

None

classmethod from_manifest(manifest, *, version=None, env_prefix=None, config_name=None, local_config=None, show_no_description=None)

Load a pre-compiled manifest produced by xclif compile.

This is a faster alternative to from_routes() — it skips the pkgutil.walk_packages + inspect.getmembers filesystem scan at the cost of a one-time xclif compile build step.

Parameters:

• manifest (ModuleType) – The generated manifest module (typically myapp._xclif_manifest).

• version (str | None) – Explicit version string. When None, auto-detected from the top-level package of manifest (same behaviour as from_routes()).

• local_config (str | None) – Filename for cwd-based local config. See Cli.

• env_prefix (str | None)

• config_name (str | None)

• show_no_description (bool | None)

Return type:

Self

classmethod from_routes(routes, *, version=None, env_prefix=None, config_name=None, local_config=None, show_no_description=None)

Build a Cli by walking a routes package at runtime.

Each module in routes that exports a Command becomes a subcommand. The package structure determines the command hierarchy — see File-Based Routing for details.

Parameters:

• routes (ModuleType) – The routes package module (e.g. import myapp.routes as routes).

• version (str | None) – Explicit version string. When None, auto-detected from the top-level package of routes.

• env_prefix (str | None) – Prefix for env-var overrides. Defaults to the uppercased root command name.

• config_name (str | None) – App name for config directory resolution. Defaults to the root command name.

• note:: (..) – For production CLIs, prefer from_manifest() to avoid the pkgutil.walk_packages overhead on every invocation.

• local_config (str | None)

• show_no_description (bool | None)

Return type:

Self

class xclif.Context(_data)

Bases: object

Read-only view of cascading framework state.

Built-in properties provide typed access to implicit options:

ctx = get_context()
ctx.verbosity  # int (0–3)
ctx.colors     # "always" | "never" | "auto"

User-defined cascading options (marked with Cascade()) are accessible via dict-style lookup:

ctx["my_option"]
ctx.get("my_option", default)

Parameters:

_data (dict)

property verbosity: int

Verbosity level (0–3). Corresponds to -v / -vv / -vvv.

property colors: str

"always", "never", or "auto".

Type:

Color mode

get(key, default=None)

Return the value for key, or default if not set.

Parameters:

• key (str)

• default (object)

Return type:

object

class xclif.Option(description=None, name=None)

Bases: object

Annotation metadata for CLI options.

Use inside Annotated to attach a description or override the flag name:

def build(dry_run: Annotated[bool, Option(description="Skip execution", name="dry-run")] = False) -> None: ...

name overrides the CLI flag (--dry-run). The Python kwarg name is unchanged.

Parameters:

• description (str | None)

• name (str | None)

class xclif.WithConfig

Bases: object

Marker for parameters that can be read from a config file or env var.

name: WithConfig[str] is sugar for Annotated[str, WithConfig()].

Priority order: CLI flag > env var > config file > default. Env var: <PREFIX>_<PARAM_NAME_UPPERCASED> Config key: the parameter name as-is.

xclif.command(*names, show_no_description=None)

Convert a function into an xclif.Command.

Names are optional. The first name is the canonical command name; any additional names become aliases (alternative names that resolve to the same command). When no names are given, the function name is used (or the module name when the function is called _).

Parameters:

• show_no_description (bool | None) – When False, suppress the “No description” placeholder in help output when no docstring is provided. When None (the default), uses the framework default (True for backward compatibility).

• names (str)

Return type:

Callable[[Callable], Command]

xclif.get_context()

Return the Context for the current command dispatch.

Raises RuntimeError if called outside of command dispatch (i.e., no command is currently being executed by the framework).

Return type:

Context

xclif.command

class xclif.command.Command(name, run, arguments=<factory>, options=<factory>, subcommands=<factory>, implicit_options=<factory>, version=None, aliases=<factory>, show_no_description=True)

Bases: object

A parsed command node in the CLI tree.

Normally you don’t construct this directly — use the command() decorator or Command.command() / Command.group() for the flat API. The file-based routing approach (Cli.from_routes) builds the tree automatically from the package layout.

Parameters:

• name (str)

• run (Callable[[...], int])

• arguments (list[Argument])

• options (dict[str, _DefinitionOption])

• subcommands (dict[str, Command])

• implicit_options (dict[str, _DefinitionOption])

• version (str | None)

• aliases (list[str])

• show_no_description (bool)

print_short_help(*, force_rich=False, force_plain=False)

Print a compact one-screen help summary to stdout.

Parameters:

• force_rich (bool)

• force_plain (bool)

Return type:

None

print_long_help(*, force_rich=False, force_plain=False)

Print the full help page (including the long description) to stdout.

Parameters:

• force_rich (bool)

• force_plain (bool)

Return type:

None

print_agent_help()

Print a hyper-short, token-efficient help summary for LLM agents.

Automatically used when stdout is not a TTY (e.g. piped to another process or called by an agent). Recursively flattens the entire command tree and filters out framework-owned implicit options and hidden subcommands like completions.

Example output:

myapp: My application.

greet NAME - Greet someone. Options: --template STR (default: 'Hello, {}!')
config get - Print the current config.
config set KEY VALUE - Set config values.

Return type:

None

command(*names)

Register a subcommand on this command using the decorator API.

This is the flat API alternative to file-based routing. For large codebases where better scaling is desirable, consider the manifest compiler (xclif compile) instead, which pre-builds a static manifest and avoids the filesystem walk cost of Cli.from_routes.

Parameters:

names (str)

Return type:

Callable[[Callable], Command]

group(name)

Create an empty subcommand group on this command.

Part of the flat decorator API. For large codebases where better scaling is desirable, consider the manifest compiler (xclif compile) to pre-build a static manifest instead.

Parameters:

name (str)

Return type:

Command

execute(args=None, context=None)

Parse args and run the appropriate subcommand, returning an exit code.

When args is None, sys.argv[1:] is used. Pass an explicit list for testing without subprocess overhead:

assert my_command.execute(["greet", "Alice"]) == 0

Parameters:

• args (list[str] | None)

• context (dict | None)

Return type:

int

property description: str

Full docstring of the command’s run function, cleaned by inspect.getdoc.

property short_description: str

First line of description, used in subcommand listings.

xclif.command.command(*names, show_no_description=None)

Convert a function into an xclif.Command.

Names are optional. The first name is the canonical command name; any additional names become aliases (alternative names that resolve to the same command). When no names are given, the function name is used (or the module name when the function is called _).

Parameters:

• show_no_description (bool | None) – When False, suppress the “No description” placeholder in help output when no docstring is provided. When None (the default), uses the framework default (True for backward compatibility).

• names (str)

Return type:

Callable[[Callable], Command]

xclif.definition

class xclif.definition.Argument(name, converter, description, variadic=False, config=None, choices=None)

Bases: Generic

A positional argument on a command.

Created automatically from a function signature by the command() decorator. Use Arg inside Annotated to attach a description or display name.

Parameters:

• name (str)

• converter (Callable[[Any], T])

• description (str)

• variadic (bool)

• config (WithConfig | None)

• choices (list[str] | None)

property short_description: str

First line of description, used in compact help output.

xclif.context

Dispatch context — exposes cascading framework state to user code.

class xclif.context.Context(_data)

Bases: object

Read-only view of cascading framework state.

Built-in properties provide typed access to implicit options:

ctx = get_context()
ctx.verbosity  # int (0–3)
ctx.colors     # "always" | "never" | "auto"

User-defined cascading options (marked with Cascade()) are accessible via dict-style lookup:

ctx["my_option"]
ctx.get("my_option", default)

Parameters:

_data (dict)

property verbosity: int

Verbosity level (0–3). Corresponds to -v / -vv / -vvv.

property colors: str

"always", "never", or "auto".

Type:

Color mode

get(key, default=None)

Return the value for key, or default if not set.

Parameters:

• key (str)

• default (object)

Return type:

object

xclif.context.get_context()

Return the Context for the current command dispatch.

Raises RuntimeError if called outside of command dispatch (i.e., no command is currently being executed by the framework).

Return type:

Context

xclif.errors

exception xclif.errors.UsageError(message, hint=None)

Bases: Exception

A user-facing CLI invocation error.

Parameters:

• message (str)

• hint (str | None)

Return type:

None

xclif.compiler

See the Manifest Compiler guide.