argbuilder
CLI bugs should fail in your test, not in your user's terminal.
argbuilder is a zero-dependency Python CLI builder with a checkable
correctness contract. A broken definition raises AssertionError at the
builder call — or at build, for rules that span arguments. A broken command
line comes back as a structured Error from try_get_matches_from, so a
test can assert on it; get_matches() prints it and exits.
Parsing itself is pure: try_get_matches_from(argv, env=...) never reads
sys.argv, os.environ or the terminal, so the CLI contract can be verified
in one fast test — no subprocess, no terminal, no mocked environment.
The clap model, for Python: immutable builders, typed getters, and one source of truth for help, Markdown docs and shell completion.
Python 3.12+ · no dependencies · github.com/Tomperez98/argbuilder
from argbuilder import Arg, Command
def cli() -> Command:
return (
Command("greet")
.arg(Arg("name").required(True))
.arg(
Arg("times")
.long("times")
.env("GREET_TIMES")
.value_parser(range(1, 6))
.default_value("1")
)
)
if __name__ == "__main__":
matches = cli().get_matches() # reads sys.argv + os.environ, exits on error
name = matches.get_required("name", str) # required(True): never None
times = matches.get_required("times", int) # defaulted: never None
for _ in range(times):
print(f"hello, {name}")
$ greet Ada --times 6
error: invalid value '6' for '--times <TIMES>': 6 is not in 1..=5
Usage: greet [OPTIONS] <NAME>
For more information, try '--help'.
Verify the same CLI without a process:
from argbuilder import ArgMatches
def test_cli() -> None:
cli().debug_assert() # the definition is legal
matches = cli().try_get_matches_from(["greet", "Ada"], env={"GREET_TIMES": "3"})
assert isinstance(matches, ArgMatches)
assert matches.get_required("times", int) == 3
A fuller CLI with subcommands is in examples/git.py
(uv run examples/git.py --help).
Built for the edit → verify loop
This is the property that matters when a coding agent is writing the CLI: the agent does not have to remember to test every failure mode, because most of the mechanical ones cannot pass silently.
- Definition bugs fail at the definition. Duplicate shorts, a default the
parser rejects,
required(True)plus a default,short("ab")— anAssertionErrornames the command and argument. Cross-argument rules fail at build ordebug_assert(). Raised explicitly, sopython -Odoes not strip it. - Reads are typed at the call site.
get_required("port", int)returns anintor raises there.get_oneisT | None;get_manyis a tuple;get_flagis abool. No dictionary lookups, no stringly-typed parsed values, and the optional case is explicit. - The parser is pure.
try_get_matches_from(argv, env={...})never touchessys.argv,os.environ, or the terminal. Tests are deterministic, fast, and parallel. - Errors are data.
ErrorKindis a union of frozen dataclasses. MatchInvalidValue(...)orUnknownArgument(suggestion="--port"); do not regex a message. - One definition, every output. Help, Markdown docs and shell completion render from the same tree; the pure renderers make drift a test failure.
What the contract catches: invalid CLI structure, wrong getter/type/ action, unknown ids, invalid values, missing required arguments, conflicts, and contradictory requirements.
What it does not: what your main does with the parsed values. argbuilder
checks the CLI boundary, not your business logic.
Working with a coding agent? Put AGENTS.md in context.
Install
uv add argbuilder
# or
pip install argbuilder
Python 3.12+ and no dependencies. To track an unreleased main instead of a
release:
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
| Who made the mistake | Example | What happens |
|---|---|---|
| You, defining the CLI | two args claim -v, required(True) plus a default, a default the parser rejects, short("ab"), an argument reusing the reserved id help / version |
AssertionError, naming the command and argument. Builder-local mistakes fail at the builder call, cross-argument ones at build. Raised explicitly, so python -O doesn't strip them. |
| You, reading matches | unknown id, get_one("port", str) on an int, get_one on an Append arg, get_flag on a value arg, get_required on an arg that can be absent |
AssertionError at the call |
| The user, typing the command | unknown flag, bad value, missing required arg, --help |
try_get_matches_from returns an Error. get_matches prints it and exits (0 for help/version, 2 otherwise). |
That second row is why matches are read with typed getters, not a dictionary:
| Getter | Use it for |
|---|---|
get_required(id, T) |
an arg that is required(True) or has a default — never None |
get_one(id, T) |
an optional value, as T | None |
get_many(id, T) |
append and multi-value args: a tuple, empty when absent |
get_flag(id) |
a set_true / set_false flag, as bool |
get_count(id) |
a count flag, as int |
contains_id(id) |
whether a value is present from any source, defaults included |
value_source(id) |
"default_value", "env_variable" or "command_line" |
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
Post-parse validation uses the same error format through
ArgMatches.error() (or Command.error()):
from argbuilder import ValueValidation
matches.error(ValueValidation(), "--from must precede --to").exit()
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_COLORis set orTERM=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)))
Shell completion
The completion command
Enable a visible completion <SHELL> command with one builder call on the
root command:
cli = Command("mycli").completion_subcommand(True)
Then load completion for the current shell session, with no files to copy:
# bash
eval "$(mycli completion bash)"
# zsh
eval "$(mycli completion zsh)"
# fish
mycli completion fish | source
# PowerShell
mycli completion powershell | Out-String | Invoke-Expression
Nothing is written to ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish or
$PROFILE; completion lasts until the session ends. To keep it, source the
same command from a startup file or install a generated script where the
shell looks for completions.
The command is opt-in, listed in help, and accepted only on the root command;
a nested completion_subcommand(True) is a definition bug. The executable
must be on PATH under the same name as Command(...): running a file as
python mycli.py does not create a mycli executable.
get_matches() and get_matches_from() print the script to stdout and exit 0.
try_get_matches_from() stays pure: it returns the parsed ArgMatches and
never prints or exits. A custom parser that only calls try_get_matches_from()
must call render_completion() itself.
Generated scripts
cmd.render_completion(shell) returns a completion script for bash, zsh,
fish or powershell. The script is a thin adapter: it calls the program as
tool __complete <cursor> <argv...>, and get_matches() answers that request
before parsing. There is no hidden command to add, and no regeneration step in
the hot path.
Generate the script wherever you already generate docs:
from pathlib import Path
command = cli()
Path("tool.bash").write_text(command.render_completion("bash"))
Path("_tool").write_text(command.render_completion("zsh"))
Path("tool.fish").write_text(command.render_completion("fish"))
Path("tool.ps1").write_text(command.render_completion("powershell"))
Install it the way each shell expects:
- bash:
source tool.bashfrom~/.bashrc, or put it in/etc/bash_completion.d/. Bash 3.2 (macOS) is supported; bash 4+ can also honour the directory-only and no-file directives. - zsh: save the output as
_toolin a directory on$fpath, then runcompinit. - fish: save it as
~/.config/fish/completions/tool.fish. - PowerShell:
. tool.ps1from$PROFILE.
Candidates come from Command.complete(argv, cursor), which walks the same
resolved command tree as the parser and returns a CompletionResult plus a
CompletionDirective. It is pure and directly testable:
result = command.complete(["git", "push", "--color", ""])
assert "auto" in [candidate.value for candidate in result.candidates]
Point shell completion at paths and directories:
Arg("config").long("config").value_hint("file")
Arg("workdir").long("workdir").value_hint("dir")
ValueHint supports any_path, file, executable (file completion) and
dir (directory-only completion). clap's command, username, hostname
and env_var hints are not accepted: they need shell-specific knowledge this
package does not implement, so accepting them would silently do nothing.
Hidden arguments and hidden subcommands are never offered; use
Command("__internal").hide(True) for those. hide(True) applies to
subcommands only. The generated scripts rely on get_matches();
get_matches_from() also handles the completion command. If an application
uses try_get_matches_from() directly, it should call complete() and
render_completion() itself.
Directive support varies by shell. zsh honours file, directory-only and
no-file completion. bash 4+ honours directory-only and no-file completion;
bash 3.2 always lets the shell fall back to files. fish can suppress file
completion, but neither fish nor PowerShell can restrict completion to
directories, so dir still offers files there. Path hints apply to a separate
value word: --config completes paths, while --config= suppresses path
completion, so --config=path has to be typed in full. Choice values such as
--color=auto are completed by the engine either way. For a
require_equals() option, completion offers the option name; type = before
the value. Offering the trailing = itself needs per-shell no-space support
and is still a follow-up.
Markdown 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, hidden aliases and hidden subcommands
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.
For agent-facing context, see AGENTS.md; for a compact index
that LLM tools can fetch first, see llms.txt.
clap → argbuilder
Coming from clap? The builder API maps almost one to one:
| clap | argbuilder |
|---|---|
Command::new("x") / Arg::new("x") |
Command("x") / Arg("x"), both immutable (each method returns a new value) |
.value_parser(value_parser!(u16).range(1..)) |
.value_parser(range(1, 65536)), ValueParser.integer(min=1) |
.value_parser(["a", "b"]), ValueEnum |
.value_parser(["a", "b"]), .value_parser(Mode) with type Mode = Literal["a", "b"] |
value_parser!(PathBuf) |
.value_parser(Path). Any str -> T callable works, and a ValueError becomes a user error. |
ArgAction::{Set, Append, SetTrue, SetFalse, Count, Help, Version} |
"set", "append", "set_true", "set_false", "count", "help", "version" (default: "set") |
ValueSource::{DefaultValue, EnvVariable, CommandLine} |
"default_value", "env_variable", "command_line" |
ErrorKind::InvalidValue, plus Error::get(ContextKind::…) |
InvalidValue(argument, value, reason, …): the context is fields on the kind |
.num_args(1..), .num_args(0..=1), .num_args(2) |
.num_args(1, None), .num_args(0, 1), .num_args(2) |
get_one::<T>, get_many::<T>, get_flag, get_count |
get_one(id, T), get_many(id, T) (a tuple, empty if absent), get_flag, get_count |
get_one::<T>(id).expect(..) on a required or defaulted arg |
get_required(id, T) |
try_get_matches_from → Result<ArgMatches, Error> |
try_get_matches_from → ArgMatches | Error |
Error::exit, ErrorKind, Command::error |
Error.exit(), ErrorKind, Command.error(), and ArgMatches.error() for the subcommand you're in |
Arg::global(true) |
.global_(True) (global is a Python keyword). See below for how repeats work. |
Arg::last(true) |
.last(True): a positional filled only after a literal --, taking every token after it verbatim (mytool run -- cargo build --release). |
Arg::require_equals(true) |
.require_equals(True): only --color=always / -c=always; the next token is never consumed. |
Arg::allow_negative_numbers(true) |
.allow_negative_numbers(True): -5, -0.5, -1.5e-3 are values; other hyphen tokens still parse as flags. |
Arg::trailing_var_arg(true) |
.trailing_var_arg(True): after the first value, every token is captured verbatim, with no --. |
Arg::overrides_with, Arg::exclusive |
.overrides_with(id), .overrides_with_all(ids), .exclusive(True). |
Arg::required_unless_present, Arg::required_if_eq |
The same names. |
Command::args_conflicts_with_subcommands(true) |
.args_conflicts_with_subcommands(True). |
alias, visible_alias, short_alias, visible_short_alias |
The same names, on Arg and (alias / visible_alias) on Command. Call once per alias. |
the help subcommand, disable_help_subcommand |
The same: git help, git help push |
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"
require_equals(True) applies to both spellings of an option: --color=always
and -c=always work, while --color always, -c always and -calways are
errors. It only applies to value-taking options with short() or long();
a positional has no = spelling. With num_args(0, 1), a bare --color
still selects the argument and uses default_missing_value() or no value,
and never consumes the next token. value_delimiter() may split the single
inline value, so --tags=a,b can produce several values.
allow_negative_numbers(True) accepts the plain negative numeric grammar
-5, -0.5, -1.5e-3 (no underscores, nan, inf, or bare -). It works
for options and positionals; -x still parses as a flag. A digit short such
as -5 cannot coexist with it on the same command, because both would claim
the same token.
trailing_var_arg(True) is the no--- wrapper mode:
mytool run cargo build --release stores ("cargo", "build", "--release").
It must be the final positional with num_args(..., None) and cannot be
combined with last() or allow_hyphen_values(). A subcommand name still
wins before the trailing positional starts; a later -- is a value.
overrides_with(id) is last-one-wins: using the argument removes earlier
command-line values of id. Defaults and environment values are not erased;
they become effective again if the overridden argument has no explicit value.
Both arguments must be global or both local, and an argument cannot both
override and conflict with the same target. exclusive(True) reports an
ArgumentConflict when any other argument is explicit; defaults do not count,
environment values do.
required_unless_present(id) requires an argument unless id has a value
from the command line or environment, or has a user-written default. A flag's
implicit False/0 does not count. required_if_eq(id, value) requires the
argument when id's effective raw spelling equals value; the comparison is
on the raw command-line, environment or default string, not the parsed value.
Both forms combine all missing arguments into one MissingRequiredArgument.
A conditional argument is a definition bug if it is also required(True) or
has a default.
args_conflicts_with_subcommands(True) makes a command's own arguments
mutually exclusive with its subcommands: stash --message wip and
stash push file work, while mixing them returns SubcommandConflict.
Defaults and environment values do not count as parent arguments, but an
explicit parent global does; a global given only inside the subcommand does
not. A required parent argument or required group would make every subcommand
unusable, so that combination panics when the command is built.
Also supported: env, default_value(s), default_missing_value,
conflicts_with(_all), requires, overrides_with(_all), exclusive,
required_unless_present, required_if_eq, ArgGroup (required, multiple),
allow_hyphen_values, allow_negative_numbers, require_equals,
value_delimiter, last, trailing_var_arg, hide, value_hint,
args_conflicts_with_subcommands, 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'").
-h/--help and -V/--version are added for you. help and version are
reserved ids: an argument with one of them must use the matching help /
version action (which replaces the automatic flag) or be renamed.
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
Everything CI runs — lint, format, type check, the tests at 100% branch
coverage, a build-and-import smoke test of the wheel, and the shape and
behavior contract checks — is one mise task:
mise run ci
The pieces on their own:
uv run ruff check # lint
uv run ruff format --check # format
uv run ty check --error-on-warning # type check, warnings fatal
uv run pytest # tests
mise run contract:check # this build against this spec
mise run contract:compat # this build against the last release
The contract tasks need the .NET SDK (global.json pins it).
CI runs the fast checks once and the tests on Python 3.12–3.15
(.github/workflows/ci.yml). To release, write
the CHANGELOG.md entry and bump the version in the same PR
(uv version --bump patch), merge it, then run mise run release:tag: the
tag triggers release.yml, which publishes
to PyPI and then checks the published package
(release_validate.yml, also run
weekly). The full checklist and the recovery steps for a failed release are
in RELEASING.md.
Metadata
Release files for argbuilder 2.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| argbuilder-2.0.1.tar.gz | 52.6 kB | Without provenance | Details for argbuilder-2.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| argbuilder-2.0.1-py3-none-any.whl | Python 3 | none | any | Details for argbuilder-2.0.1-py3-none-any.whl |
Total release size: 113.0 kB
Release files / argbuilder-2.0.1.tar.gz
| Download URL | argbuilder-2.0.1.tar.gz |
|---|---|
| Size | 52.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f61a6fd6016a72f35950d79b2a7635117f5088641ee486cf3fc5a4a88848a0b2
|
|
BLAKE2b-256 checksum How to use checksums |
384d525caeb69085b859760d391ae11b1b1e30494298f92fcf63e5fbe7682f83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / argbuilder-2.0.1-py3-none-any.whl
| Download URL | argbuilder-2.0.1-py3-none-any.whl |
|---|---|
| Size | 60.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a32a080b81a6de47a39096be18fb08244aeb104144fe719511c6f3314ea5587e
|
|
BLAKE2b-256 checksum How to use checksums |
d58b27703e0127a75de291cafe7f010f52f3b4767e0459e8fdb9b1550183e839
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for argbuilder 2.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.