Commands declare their interface by implementing four parameter list methods:

• getRequiredNamedParameterList()
• getOptionalNamedParameterList()
• getRequiredParameterList()
• getOptionalParameterList()

Named parameters map to positional values (deploy production api), while Parameter definitions map to options and flags (--tag v1.2.3, --verbose).

¶Defining command contracts

public function getRequiredNamedParameterList():array {
	return [
		new NamedParameter("environment"),
	];
}

public function getOptionalNamedParameterList():array {
	return [
		new NamedParameter("service"),
	];
}

public function getRequiredParameterList():array {
	return [
		new Parameter(true, "tag", "t", "Release tag to deploy"),
	];
}

public function getOptionalParameterList():array {
	return [
		new Parameter(false, "dry-run", "d", "Preview only"),
		new Parameter(false, "verbose", "v", "Show extra detail"),
	];
}

¶Unrecognised options

It’s easy to mistype an option when you’re working at the terminal. Long options such as --verbose and short options such as -v are only recognised when they appear in the command’s required or optional parameter list. If you supply an unknown option, you’ll get a helpful error rather than having it silently ignored.

For example, using the command above:

$ deploy production --tag v1.2.3 --verbsoe
Error: Invalid argument supplied: "--verbsoe"

The application also prints the command’s usage to the error stream and exits with code 1, without running the command. Correct the spelling to --verbose and you’re ready to go.

The same behaviour applies to options with values, such as --unknown=value or -x=value. Each option in a short-option chain is checked individually: -dv is valid for the command above, while -dx reports Invalid argument supplied: "-x". Use the declared long name after -- and the declared short name after -; --v is not an alias for --verbose.

The built-in --help and --version options remain available without adding them to your parameter lists. Extra positional values are still available as user data; this check applies to options beginning with a dash.

If you’re calling Command::checkArguments() or Command::getArgumentValueList() directly, an unknown option throws GT\Cli\Argument\InvalidArgumentException.

¶Reading values in run()

$environment = (string)$arguments->get("environment");
$service = (string)$arguments->get("service", "web");
$tag = (string)$arguments->get("tag");
$dryRun = $arguments->contains("dry-run");
$verbose = $arguments->contains("verbose");

The get($key, $default) pattern allows simple defaults for optional values, while contains($key) is used for boolean flags.

¶Type-safe getters

Each ArgumentValue can return its next queued value as a native scalar type:

$workers = $arguments->get("workers", "1")->getInt();
$threshold = $arguments->get("threshold", "0.75")->getFloat();
$label = $arguments->get("label", "release")->getString();
$enabled = $arguments->get("enabled", "0")->getBool();

The available getters are getString(), getInt(), getFloat() and getBool(). They use PHP’s scalar conversion rules and, like get(), consume one value each time they are called. Continue to use contains() for valueless flags such as --verbose.

When required values are missing, command execution fails with explicit exceptions (MissingRequiredParameterException, MissingRequiredParameterValueException) and usage text is printed automatically.

---

Next, see coloured output for consistent terminal styling.