Group Constraints
Mutually Exclusive Groups
Mutually exclusive means “at most one of these arguments may be provided”. If the user supplies two or more arguments from the same group, parsing fails.
This is useful when two options are logically contradictory, such as --json vs
--yaml (you can only pick one output format), or --color vs --no-color.
Defining a group
command.add_argument(Argument("json", help="Output as JSON").long["json"]().flag())
command.add_argument(Argument("yaml", help="Output as YAML").long["yaml"]().flag())
command.add_argument(Argument("csv", help="Output as CSV").long["csv"]().flag())
var group: List[String] = ["json", "yaml", "csv"]
command.mutually_exclusive(group^)
myapp --json # OK — only one from the group
myapp --yaml # OK
myapp # OK — none from the group is also fine
myapp --json --yaml # Error: Arguments are mutually exclusive: '--json', '--yaml'
myapp --json --csv # Error: Arguments are mutually exclusive: '--json', '--csv'
Works with value-taking options too
The group members don’t have to be flags — they can be any kind of argument:
command.add_argument(Argument("input", help="Read from file").long["input"]())
command.add_argument(Argument("stdin", help="Read from stdin").long["stdin"]().flag())
var io_group: List[String] = ["input", "stdin"]
command.mutually_exclusive(io_group^)
myapp --input data.csv # OK
myapp --stdin # OK
myapp --input data.csv --stdin # Error: mutually exclusive
Multiple groups
You can register more than one exclusive group on the same command:
var format_group: List[String] = ["json", "yaml", "csv"]
command.mutually_exclusive(format_group^)
var color_group: List[String] = ["color", "no-color"]
command.mutually_exclusive(color_group^)
Each group is validated independently — using --json and --no-color together
is fine, because they belong to different groups.
| Scenario | Example |
|---|---|
| Conflicting output formats | --json / --yaml / --csv |
| Boolean toggle pair | --color / --no-color |
| Exclusive input sources | --file <path> / --stdin |
| Verbose vs quiet | --verbose / --quiet |
Note: Pass the
List[String]with^(ownership transfer).
One-Required Groups
A one-required group declares that at least one argument from the group must be provided. Parsing fails if none are present. This is useful for ensuring the user specifies a mandatory choice — for example, an output format or an input source.
This mirrors Go cobra’s MarkFlagsOneRequired and Rust clap’s
ArgGroup::required.
Defining a one-required group
command.add_argument(Argument("json", help="Output as JSON").long["json"]().flag())
command.add_argument(Argument("yaml", help="Output as YAML").long["yaml"]().flag())
var format_group: List[String] = ["json", "yaml"]
command.one_required(format_group^)
myapp --json # OK (one provided)
myapp --yaml # OK (one provided)
myapp # Error: At least one of the following arguments is required: '--json', '--yaml'
myapp --json --yaml # OK (at least one is satisfied — both is fine for one_required alone)
Note that one_required only checks that at least one is present. It does
not prevent multiple from being used. To enforce exactly one, combine it
with mutually_exclusive:
Exactly-one pattern (one-required + mutually exclusive)
command.add_argument(Argument("json", help="Output as JSON").long["json"]().flag())
command.add_argument(Argument("yaml", help="Output as YAML").long["yaml"]().flag())
var excl: List[String] = ["json", "yaml"]
var req: List[String] = ["json", "yaml"]
command.mutually_exclusive(excl^)
command.one_required(req^)
myapp --json # OK
myapp --yaml # OK
myapp # Error: At least one of the following arguments is required: '--json', '--yaml'
myapp --json --yaml # Error: Arguments are mutually exclusive: '--json', '--yaml'
Works with value-taking options
command.add_argument(Argument("input", help="Input file").long["input"]().short["i"]())
command.add_argument(Argument("stdin", help="Read from stdin").long["stdin"]().flag())
command.one_required(["input", "stdin"])
myapp --input data.txt # OK
myapp --stdin # OK
myapp # Error: At least one of the following arguments is required: '--input', '--stdin'
Multiple one-required groups
You can declare multiple groups. Each is validated independently:
command.one_required(["json", "yaml"])
command.one_required(["input", "stdin"])
myapp --json --input f.txt # OK (both groups satisfied)
myapp --json # Error (source group unsatisfied)
| Scenario | Example |
|---|---|
| Tags / labels | --tag release --tag stable |
| Include paths | -I /usr/lib -I /opt/lib |
| Target environments | --env dev --env staging |
| Compiler defines | --define DEBUG --define VERSION=2 |
Required-Together Groups
Required together means “if any one of these arguments is provided, all the others must be provided too”. If only some are given, parsing fails.
This is useful for sets of arguments that only make sense as a group — for
example, authentication credentials (--username and --password), or network
settings (--host, --port, --protocol).
Defining a group (Required-Together)
command.add_argument(Argument("username", help="Auth username").long["username"]().short["u"]())
command.add_argument(Argument("password", help="Auth password").long["password"]().short["p"]())
var group: List[String] = ["username", "password"]
command.required_together(group^)
myapp --username admin --password secret # OK — both provided
myapp # OK — neither provided
myapp --username admin # Error: Arguments required together:
# '--password' required when '--username' is provided
myapp --password secret # Error: Arguments required together:
# '--username' required when '--password' is provided
Three or more arguments
Groups can contain any number of arguments:
command.add_argument(Argument("host", help="Host").long["host"]())
command.add_argument(Argument("port", help="Port").long["port"]())
command.add_argument(Argument("proto", help="Protocol").long["proto"]())
var net_group: List[String] = ["host", "port", "proto"]
command.required_together(net_group^)
myapp --host localhost --port 8080 --proto https # OK
myapp --host localhost # Error: '--port', '--proto' required when '--host' is provided
Combining with mutually exclusive groups
Required-together and mutually exclusive can coexist on the same command:
# These two must appear together
var auth: List[String] = ["username", "password"]
command.required_together(auth^)
# These two cannot appear together
var excl: List[String] = ["json", "yaml"]
command.mutually_exclusive(excl^)
| Scenario | Example |
|---|---|
| Authentication pair | --username + --password |
| Network connection | --host + --port + --protocol |
| TLS settings | --cert + --key |
| Database connection | --db-host + --db-user + --db-pass |
Note: Pass the
List[String]with^(ownership transfer).
Conditional Requirements
Sometimes an argument should only be required when another argument is present.
For example, --output might only make sense when --save is also provided.
command.add_argument(Argument("save", help="Save results").long["save"]().flag())
command.add_argument(Argument("output", help="Output file").long["output"]().short["o"]())
command.required_if("output", "save")
This means: if --save is provided, then --output must also be provided.
myapp --save --output out.txt # OK — both present
myapp --save # Error: '--output' is required when '--save' is provided
myapp --output file.txt # OK — condition not triggered
myapp # OK — neither present
Multiple conditional rules
You can declare multiple conditional requirements on the same command:
command.required_if("output", "save") # --output required when --save
command.required_if("format", "compress") # --format required when --compress
Each rule is checked independently after parsing.
Error messages
Error messages use --long display names when available:
Error: Argument '--output' is required when '--save' is provided
| Scenario | Example |
|---|---|
| Save to file | --output required when --save |
| Compression settings | --format required when --compress |
| Custom export configuration | --template required when --export |
Difference from
required_together():required_together()is symmetric — if any argument from the group appears, all must appear.required_if()is one-directional — only the target is required when the condition is present, not vice versa.
Mutual Implication
Use implies() to declare that setting one argument automatically sets another.
This is useful when one mode logically entails another — for example, debug mode
should always enable verbose output.
command.add_argument(Argument("debug", help="Debug mode").long["debug"]().flag())
command.add_argument(Argument("verbose", help="Verbose output").long["verbose"]().short["v"]().flag())
command.implies("debug", "verbose")
This means: if --debug is provided, --verbose is automatically set too.
myapp --debug # OK — --verbose is auto-set
myapp --debug -v # OK — --verbose already set, no conflict
myapp --verbose # OK — --debug is NOT set (one-directional)
myapp # OK — neither set
Chained implications
Implications can be chained. If A implies B and B implies C, then setting A will also set C:
command.implies("debug", "verbose")
command.implies("verbose", "log")
# --debug → --verbose → --log (all three are set)
Multiple implications from one trigger
A single argument can imply multiple targets:
command.implies("debug", "verbose")
command.implies("debug", "log")
# --debug sets both --verbose and --log
Works with count arguments
When the implied argument is a count (.count()), it is set to 1 if not already
present. Explicit counts are preserved:
command.add_argument(Argument("verbose", help="Verbosity").long["verbose"]().short["v"]().count())
command.implies("debug", "verbose")
# --debug → verbose count = 1
# --debug -vvv → verbose count = 3 (explicit value kept)
Cycle detection
Circular implications are detected at registration time and raise an error:
command.implies("a", "b")
command.implies("b", "a") # Error: cycle detected
This also catches indirect cycles (A → B → C → A).
Integration with other constraints
Implications are applied after defaults and before validation, so implied arguments participate in all subsequent constraint checks:
command.implies("debug", "verbose")
command.required_if("output", "verbose")
# --debug implies --verbose, which triggers the conditional requirement for --output
command.implies("debug", "verbose")
var excl: List[String] = ["verbose", "quiet"]
command.mutually_exclusive(excl^)
# --debug --quiet fails: --debug implies --verbose, which conflicts with --quiet
| Scenario | Example |
|---|---|
| Debug enables verbose | implies("debug", "verbose") |
| Verbose enables logging | implies("verbose", "log") |
| Strict enables all checks | implies("strict", "lint") + implies("strict", "typecheck") |
Difference from
required_if():required_if()requires the user to provide the target argument — parsing fails if they don’t.implies()automatically sets the target — no user action needed.