Home

phpgt/cli is a command line interface builder for creating multi-command terminal applications with typed arguments, option parsing, usage generation and testable I/O streams.

The primary entry point is the Application class, which coordinates command discovery, argument parsing and output handling. Commands extend Gt\Cli\Command\Command and declare their contract through required/optional named parameters and required/optional flags/options.

The purpose of this library is to keep command line tools explicit and maintainable. Instead of reading raw $argv manually, each command receives an ArgumentValueList, giving predictable access to passed values and reducing parsing errors.

Beyond argument parsing, this library includes built-in help and version commands, stream abstraction for unit testing, colour-aware output through Palette, and interactive terminal helpers such as cursor movement and progress bars.

A typical example

The following script is a minimal command from example/02-greeter.php.

$greeterCommand = new class extends Command {
	public function run(?ArgumentValueList $arguments = null):int {
		$name = (string)$arguments->get("name", "you");
		$this->output("Hello, $name!");
		return 0;
	}

	public function getName():string {
		return "greet";
	}

	public function getDescription():string {
		return "Greet a person by name";
	}

	public function getRequiredNamedParameterList():array {
		return [];
	}

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

	public function getRequiredParameterList():array {
		return [];
	}

	public function getOptionalParameterList():array {
		return [];
	}
};

The command takes an optional positional argument (name) and falls back to you when no value is passed, producing either Hello, Greg! or Hello, you!.

Command exit codes

Command::run() must return an int exit code.

• Return 0 for success.
• Return a non-zero code to end the application with that code.

This gives commands a predictable way to exit early and makes CLI return-code handling explicit.

---

In the next section we will walk through all bundled examples.

You can also jump ahead to progress bars for in-place terminal updates.