celemas/cli

Celemas cli tools runner

0.2.0 2026-05-10 21:34 UTC

Requires

• php: ^8.5

Requires (Dev)

• celemas/dev: ^4.0

MIT

• Ernst

• cli
• celemas

Published on Packagist.org on 2026-05-10 21:38 UTC

README

A command line interface helper.

Features

• Simple command creation with automatic help generation
• Parsed options and positional arguments via an injected Args object
• Built-in color support for terminal output
• Command help with php run help <command> or php run <command> --help
• Built-in commands command for shell autocomplete
• --key=value options (repeatable) and boolean --flag / -h flags
• Output helpers: info(), success(), warn(), error(), echoln() (warnings and errors go to STDERR)
• Text indentation and wrapping with indent()
• Debug mode for detailed error traces
• 100% test coverage

Installation

composer require celemas/cli

Quick Start

Create a command by extending Celemas\Cli\Command:

use Celemas\Cli\{Args, Command};

class MyCommand extends Command {
    protected string $name = 'mycommand';
    protected string $group = 'MyGroup';
    protected string $description = 'This is my command';

    public function run(Args $args): int
    {
        $name = $args->positional(0, 'world');
        $this->info("Running my command for {$name}");
        $this->success("Command completed!");

        return self::SUCCESS;
    }
}

Options use --key=value (a bare --flag is a boolean); every other argument is a positional. Read them from the injected Args:

$name = $args->positional(0);        // first positional, or null
$conn = $args->opt('--conn', 'sqlite'); // option value, or the default
$force = $args->has('--force');      // boolean flag

Create a runner script and pass its exit code to exit():

<?php
require __DIR__ . '/vendor/autoload.php';

use Celemas\Cli\{Runner, Commands};

$commands = new Commands([new MyCommand()]);
$runner = new Runner($commands);

exit($runner->run());

Run your command:

$ php run mycommand alice
Running my command for alice
Command completed!

License

This project is licensed under the MIT license.