Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.


ScenarioExample
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)

ScenarioExample
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^)

ScenarioExample
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

ScenarioExample
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

ScenarioExample
Debug enables verboseimplies("debug", "verbose")
Verbose enables loggingimplies("verbose", "log")
Strict enables all checksimplies("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.