Documentation

Schema Reference

Each command owns its parameters, so the hierarchy is expressed by nesting. A parameter belongs to exactly one command, and its key only needs to be unique among that command's parameters - so the same flag can appear on sibling commands. A parameter with recursive: true is inherited by every command beneath the one it belongs to.

Tool Object

The root object of a Commandly tool description.

Field	Type	Required	Description
`binaryName`	string	✓	Unique CLI binary name for the tool, such as `httpx` or `curl`.
`displayName`	string	✓	Human-readable display name.
`interactive`	boolean	-	If `true`, invoking the root tool opens an interactive session or prompt.
`info`	ToolInfo Object	-	Metadata about the tool, including the homepage URL.
`installation`	Installation Object	-	Structured installation sources for the tool.
`commands`	Command Object[]	✓	Top-level commands. Subcommands are nested on their parent.
`parameters`	Parameter Object[]	✓	Parameters accepted by the tool itself, before a command is chosen.
`exclusionGroups`	ExclusionGroup Object[]	-	Groups of the tool's own parameters that are mutually exclusive or required.
`metadata`	ToolMetadata Object	-	Custom metadata.

ToolInfo Object

Field	Type	Required	Description
`description`	string	-	Short description of the tool.
`version`	string	-	Tool version string.
`url`	string	-	URL to the tool's homepage or repository.

Installation Object

Structured installation instructions for the tool.

Field	Type	Required	Description
`sources`	InstallationSource[]	✓	The documented ways to install the tool.

InstallationSource Object

A single documented way to install the tool.

Field	Type	Required	Description
`key`	string	✓	Unique identifier for this source within the tool.
`method`	InstallationMethod	✓	How the tool is installed.
`manager`	string	-	Package manager name. Only set when `method` is `package_manager` (e.g. `"brew"`, `"go"`).
`command`	string	✓	The command that installs the tool.
`url`	string	-	Documentation URL describing this installation method.
`os`	string[]	-	Platforms this source applies to: `linux`, `macos`, or `windows`. Omit when unrestricted.
`note`	string	-	Additional context, such as prerequisites or platform restrictions.

InstallationMethod

Value	Description
`package_manager`	Installed with a package manager such as `brew`, `go`, `pip`, `npm`.
`binary`	A prebuilt release binary is downloaded and unpacked.
`docker`	The tool is pulled and run as a container image.
`script`	The tool is installed by running a vendor-provided script.

Command Object

Field	Type	Required	Description
`key`	string	✓	Unique identifier for this command within the tool.
`displayName`	string	✓	Human-readable display name of the command.
`aliases`	string[]	-	Alternate spellings that invoke this command in place of `displayName`.
`description`	string	-	Human-readable description of the command.
`interactive`	boolean	-	If `true`, the command requires interactive user input at runtime. Defaults to `false`.
`sortOrder`	number	-	Display sort order.
`parameters`	Parameter Object[]	-	Parameters accepted by this command. Keys are unique among them. Omit for grouping commands.
`exclusionGroups`	ExclusionGroup[]	-	Groups of this command's parameters with mutual exclusion or required-one-of constraints.
`commands`	Command Object[]	-	Subcommands nested beneath this command.

Parameter Object

Field	Type	Required	Description
`key`	string	✓	Unique identifier among its command's parameters. For flags and options this is the full flag, dashes included (e.g. `"--output"`, `"-list"`); positional arguments use a plain name.
`displayName`	string	✓	Human-readable parameter name.
`parameterType`	ParameterType	✓	One of `Flag`, `Option`, or `Argument`.
`dataType`	ParameterDataType	✓	One of `String`, `Number`, `Boolean`, or `Enum`.
`isRequired`	boolean	-	Whether the parameter must be provided.
`isRepeatable`	boolean	-	Whether the parameter can appear more than once.
`recursive`	boolean	-	If `true`, the parameter is inherited by every command beneath the one it belongs to. A parameter on `Tool.parameters` with `recursive: true` is inherited by the whole tree. Defaults to `false`.
`description`	string	-	Human-readable description.
`group`	string	-	Display group label for UI grouping.
`aliases`	string[]	-	Short names and other spellings for `Flag` and `Option` types (e.g. `["-o"]`). The full flag is `key`.
`position`	number	-	Zero-based positional index that orders `Argument` parameters. Optional; defaults to 0.
`sortOrder`	number	-	Display sort order.
`arraySeparator`	string	-	Separator used when a repeatable parameter is joined into a single token.
`keyValueSeparator`	string	-	Character between the flag and its value. Defaults to a space.
`enum`	ParameterEnumValues Object	-	Required when `dataType` is `Enum`.
`validations`	ParameterValidation Object[]	-	Validation rules applied to the parameter value.
`dependencies`	ParameterDependency Object[]	-	Conditional relationships with other parameters.
`metadata`	ParameterMetadata Object	-	Custom metadata.

ParameterType

Value	Description
`Flag`	A boolean switch with no value (e.g. `--verbose`). Use with `dataType: Boolean`.
`Option`	A named parameter that accepts a value (e.g. `--output file.txt`).
`Argument`	A positional parameter identified by its position in the command, not a flag.

ParameterDataType

Value	Description
`String`	A string value.
`Number`	A numeric value.
`Boolean`	A boolean value. Typically used with `Flag` type.
`Enum`	One of a predefined set of values. Requires `enum`.

ParameterEnumValues Object

Field	Type	Required	Description
`values`	ParameterEnumValue Object[]	✓	Ordered list of allowed values.
`allowMultiple`	boolean	-	Whether multiple values can be selected simultaneously.
`separator`	string	-	Separator used when multiple values are combined into one token.

ParameterEnumValue Object

Field	Type	Required	Description
`value`	string	✓	The raw value passed to the CLI.
`displayName`	string	✓	Human-readable label shown in the UI.
`description`	string	-	Description of what this value does.
`isDefault`	boolean	-	Whether this value is selected by default.
`sortOrder`	number	-	Display sort order.

ExclusionGroup Object

Defines a group of parameters that are mutually exclusive or where exactly one must be chosen. Declare groups on the command that owns the parameters, or on the tool for its own parameters.

Field	Type	Required	Description
`key`	string	-	Unique identifier for the group.
`displayName`	string	✓	Human-readable group name.
`exclusionType`	ExclusionType	✓	One of `mutual_exclusive` or `required_one_of`.
`parameterKeys`	string[]	✓	Keys of the parameters belonging to this group.

ExclusionType

Value	Description
`mutual_exclusive`	At most one parameter in the group may be set at a time.
`required_one_of`	Exactly one parameter in the group must be set.

ParameterValidation Object

Field	Type	Required	Description
`key`	string	✓	Unique identifier.
`validationType`	ParameterValidationType	✓	The kind of validation to apply.
`validationValue`	string	✓	The threshold or pattern for the validation.
`errorMessage`	string	✓	Message displayed when validation fails.

ParameterValidationType

Value	Description
`min_length`	Minimum number of characters in the string value.
`max_length`	Maximum number of characters in the string value.
`min_value`	Minimum numeric value.
`max_value`	Maximum numeric value.
`regex`	Regular expression the value must match.

ParameterDependency Object

Defines a conditional relationship between two parameters.

Field	Type	Required	Description
`key`	string	✓	Unique identifier.
`parameterKey`	string	✓	Key of the parameter this dependency rule applies to.
`dependsOnParameterKey`	string	✓	Key of the parameter being depended upon.
`dependencyType`	ParameterDependencyType	✓	One of `requires` or `conflicts_with`.
`conditionValue`	string	-	Specific value of `dependsOnParameter` that activates this dependency. If omitted, the dependency applies whenever `dependsOnParameter` is set.

ParameterDependencyType

Value	Description
`requires`	This parameter can only be set if `dependsOnParameter` is also set.
`conflicts_with`	This parameter cannot be set when `dependsOnParameter` is set.

ParameterMetadata Object

Field	Type	Required	Description
`tags`	string[]	-	Custom string tags. Used to annotate parameters (e.g. `"non-configurable"`, `"output-file"`).