argbuilder

Build command-line interfaces in Python from typed, immutable builders — the clap model.

A broken definition fails when the command is built, in CI, not in front of a user. A broken command line comes back as an Error you can inspect, with the message, typo suggestion and help ready to print.

Python 3.12+ · no dependencies · github.com/Tomperez98/argbuilder

from argbuilder import Arg, Command, ValueValidation


def cli() -> Command:
    return (
        Command("git")
        .about("A fictional versioning CLI")
        .version("1.0.0")
        .subcommand_required(True)
        .arg(Arg("verbose").short("v").long("verbose").action("count"))
        .subcommand(
            Command("push")
            .about("Pushes things")
            .arg(Arg("remote").required(True))
            .arg(
                Arg("port")
                .short("p")
                .long("port")
                .value_parser(range(1, 65536))
                .env("GIT_PORT")
                .default_value("22")
            )
            .arg(Arg("force").short("f").long("force").action("set_true"))
        )
    )


if __name__ == "__main__":
    matches = cli().get_matches()  # reads sys.argv + os.environ, exits on error
    match matches.subcommand():
        case ("push", sub):
            remote = sub.get_required("remote", str)  # str: required(True), never None
            port = sub.get_required("port", int)  # int: it has a default
            force = sub.get_flag("force")  # bool
            if remote.startswith("-"):
                sub.error(ValueValidation(), "remote must not start with '-'").exit()

$ git push origin -p 99999
error: invalid value '99999' for '--port <PORT>': 99999 is not in 1..=65535

Usage: git push [OPTIONS] <REMOTE>

For more information, try '--help'.

A fuller CLI is in examples/git.py (uv run examples/git.py --help).

Or derive it from classes

Like clap's #[derive(Parser)]: fields describe the arguments, their types pick the action, and parsing returns an instance. The derive only builds a Command, so help, errors and the rules above are the same.

from __future__ import annotations  # lets Git name Clone before it's defined

from pathlib import Path

from argbuilder import Parser, arg


class Git(Parser, version="1.0.0"):
    """A fictional versioning CLI."""  # the docstring's first paragraph is `about`

    verbose: int = arg(short=True, long=True, action="count", global_=True)
    command: Clone | Push  # add `| None = None` to make it optional


class Clone(Parser):
    """Clones repos."""

    remote: str
    dir: Path | None = None


class Push(Parser):
    """Pushes things."""

    port: int = arg(short=True, long=True, value_parser=range(1, 65536), default=22)
    force: bool = arg(short=True, long=True)


git = Git.parse()  # or Git.try_parse_from(argv, env) -> Git | Error
match git.command:
    case Push(port=port, force=force):
        ...
    case Clone(remote=remote):
        ...

Without short or long a field is positional. short=True / long=True / env=True derive -d / --dry-run / DRY_RUN from the field name. Command options go on the class: name, about, version, aliases, visible_aliases, arg_required_else_help, disable_help_flag, disable_version_flag, disable_help_subcommand.

Subclasses are frozen, keyword-only dataclasses (don't add @dataclass), and type checkers see them that way. Definition bugs still panic: class options at the class statement, fields at the first to_command() or parse, since annotations may name classes defined further down. Test them with Git.to_command().debug_assert().

For anything the derive doesn't cover, extend the builder and read the result back: Git.from_arg_matches(Git.to_command().arg(...).get_matches()). The same CLI as examples/git.py, derived, is in examples/git_derive.py.

Argument types are read at runtime, so keep their imports out of if TYPE_CHECKING:. With ruff's TC rules, add:

[lint.flake8-type-checking]
runtime-evaluated-base-classes = ["argbuilder.Parser", "argbuilder.Args"]

Install

Not on PyPI yet; install from source:

uv add git+https://github.com/Tomperez98/argbuilder
# or
pip install "argbuilder @ git+https://github.com/Tomperez98/argbuilder"

The contract: bugs panic, user mistakes return values

That second row is why matches are read with typed getters, not a dictionary:

Catch definition bugs in CI the way clap recommends:

def test_cli() -> None:
    cli().debug_assert()

Test parsing with no process involved. The parser is pure, and the environment is a parameter that defaults to empty:

from argbuilder import ArgMatches

result = cli().try_get_matches_from(["git", "push", "origin"], env={"GIT_PORT": "8080"})
assert isinstance(result, ArgMatches)
sub = result.subcommand_matches("push")
assert sub is not None and sub.get_required("port", int) == 8080

Only get_matches() reads sys.argv and os.environ for parsing. Printing (Error.exit()) is the only other place that looks at the process: it checks the terminal it writes to, below.

Terminal output

When get_matches() prints help or an error, it styles the output for the stream it writes to:

• Color only on a terminal, and never when NO_COLOR is set or TERM=dumb.
• Wrapping of help text to the terminal width (or COLUMNS), capped at 100 columns. Help moves below its flag when the terminal is too narrow for two columns.

Rendering itself is pure and plain by default. Pass a Style to see what a terminal gets:

from argbuilder import Style

assert "\x1b[" not in cli().render_help()
print(cli().render_help(Style(color=True, width=60)))

Docs

cmd.render_markdown() turns a Command into a Markdown page: one # section for the command, one ## section per subcommand at any depth, named by its full path (git remote add). Content and visibility mirror render_help exactly — hidden args and hidden aliases stay out, an inherited global argument is documented again on every subcommand, the same as --help shows it there — so the two can never quietly drift apart.

from pathlib import Path

Path("docs/cli.md").write_text(cli().render_markdown())

There's no separate build step or CLI: run that wherever you'd otherwise regenerate docs (a script, a pytest golden test, a CI job) and commit the result.

clap → argbuilder

Coming from clap? The builder API maps almost one to one:

ArgAction and ValueSource are Literal strings, so a type checker catches a typo like .action("cout"), and at runtime it panics with a suggestion. ErrorKind is a union of frozen dataclasses that carry what went wrong, so you can act on an error without parsing its message:

match result.kind:
    case DisplayHelp() | DisplayVersion():
        ...
    case InvalidValue(argument=argument, value=None):
        ...  # the option was given with no value
    case UnknownArgument(argument=typed, suggestion=str(closest)):
        ...  # e.g. typed "--prot", closest "--port"

Also supported: env, default_value(s), default_missing_value, conflicts_with(_all), requires, ArgGroup (required, multiple), allow_hyphen_values, value_delimiter, last, hide, arg_required_else_help, disable_help_flag / disable_version_flag, typo suggestions for arguments, subcommands and values, and a tip when an option is used at the wrong level (git push -V: "'-V' is an option of 'git'; put it before 'push'").

A global option is read the same way at every level (matches.get_count("verbose") and sub.get_count("verbose") agree), and the whole command line counts as one list of occurrences. git -v push -v counts 2, and append values add up left to right. A set option given at two levels is an error ("cannot be used multiple times"). clap would silently keep the deeper value instead. Globals can't be positional or required, and their conflicts_with / requires may only name other globals, because every subcommand has to be able to check them.

Development

CI runs the same checks on Python 3.12–3.14 (.github/workflows/ci.yml):

uv run pytest      # tests
uv run ruff check  # lint
uv run ty check    # type check

Releases publish to PyPI from CI when a v* tag is pushed (.github/workflows/release.yml).