Constraints

Options and typed arguments can declare which combinations are valid. All three fields take option or argument names, never aliases, and they can point at either kind.

Only the inputs that the user actually provided are checked. A value that is present because of a schema default is ignored.

`exclusive`

The input must appear on its own. Nothing else is allowed alongside it, except what it lists in requires.

defineOptions({
  help: {
    schema: z.boolean().optional(),
    coerce: coerce.boolean,
    exclusive: true,
  },
});

listy --help              # fine
listy --help --verbose    # error

`requires`

The listed names have to be provided whenever this one is. Use it for inputs that make no sense on their own.

defineOptions({
  output: {
    schema: z.string().optional(),
    requires: ["input"],
  },
});

listy --output out.txt                  # error, input is missing
listy --input in.txt --output out.txt   # fine

`conflictWith`

The listed names cannot be provided together with this one.

defineOptions({
  json: {
    schema: z.boolean().optional(),
    coerce: coerce.boolean,
    conflictWith: ["table"],
  },
});

listy --json --table    # error

Tip

Skip conflictWith when exclusive is already true. Exclusive already conflicts with everything outside requires. The extra list only makes the definition harder to read.

What goes wrong

Situation	Error code
Exclusive input used with something else	`ValidationErrorCode.MutuallyExclusiveConflict`
A required name was not provided	`ValidationErrorCode.RequiredDependencyMissing`
Two conflicting inputs used together	`ValidationErrorCode.MutuallyExclusiveConflict`
A name in `requires` or `conflictWith` does not exist	`DefinitionErrorCode.UnknownRequireName`, `DefinitionErrorCode.UnknownConflictName`
A definition lists itself	`DefinitionErrorCode.SelfRequire`, `DefinitionErrorCode.SelfConflict`
The same name is in both lists	`DefinitionErrorCode.DefinitionRequiresConflictOverlap`

The definition errors are reported the first time you run the CLI, not when you write the definition.