PHPackages                             celema/console - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. celema/console

ActiveLibrary[CLI & Console](/categories/cli)

celema/console
==============

Celema console command runner

0.5.3(1mo ago)0118↓61.4%5MITPHPPHP ^8.5CI passing

Since Jan 28Pushed 1w ago1 watchersCompare

[ Source](https://github.com/celemas/console)[ Packagist](https://packagist.org/packages/celema/console)[ Docs](https://celema.dev/console)[ RSS](/packages/celema-console/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (2)Versions (11)Used By (5)

Celema Console
==============

[](#celema-console)

[![ci](https://camo.githubusercontent.com/7505d00885d052f3c9d9f03c2d8409f7c4e7d4168e41494a0ec491925ddfb67b/68747470733a2f2f636f6465666c6f652e636f6d2f63656c656d612f636f6e736f6c652f6261646765732f776f726b666c6f77732f63692e796d6c2f62616467652e7376673f7374796c653d666c6174266c6f676f3d666f7267656a6f266c6f676f436f6c6f723d7768697465266c6162656c3d6369)](https://codefloe.com/celema/console/actions)[![code coverage](https://camo.githubusercontent.com/f6aef24466c73fdf9c163513471d45e2aaa2634dd0535c775c835efff7bb9050/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d6874747073253341253246253246636f762e63656c656d612e64657625324663656c656d61253246636f6e736f6c65253246636f646525324662616467652e6a736f6e)](https://cov.celema.dev/celema/console/code)[![type coverage](https://camo.githubusercontent.com/c322581122b62c035b01a564237f3e63efceca7eb6684ac1b96430f85d270ab7/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d6874747073253341253246253246636f762e63656c656d612e64657625324663656c656d61253246636f6e736f6c65253246747970657325324662616467652d636f7665722e6a736f6e)](https://cov.celema.dev/celema/console/types)[![psalm level](https://camo.githubusercontent.com/04197615a635b5e46bb5bf619ec11d46af22aea5488b1c2ac91ca019a7dbd2a9/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d6874747073253341253246253246636f762e63656c656d612e64657625324663656c656d61253246636f6e736f6c65253246747970657325324662616467652d6c6576656c2e6a736f6e)](https://cov.celema.dev/celema/console/types)[![Software License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE.md)

A command line interface helper.

Features
--------

[](#features)

- Commands are plain classes marked with a `#[Command]` attribute — no base class, free constructors
- Automatic help generation from `#[Command]`, `#[Arg]`, and `#[Opt]` attributes
- Strict by default: the `#[Arg]`/`#[Opt]` declarations are a command's complete interface — an unknown or malformed option (with a "Did you mean" suggestion), a missing required argument, or an undeclared positional aborts before the command runs; a variadic `#[Arg]` takes open-ended input
- Parsed options and positional arguments via an injected `Args` object
- Lazy command construction: factories run only for the invoked command
- Anonymous classes as lightweight one-off commands — attributes work inline
- Built-in color support with per-stream terminal detection and `NO_COLOR`/`FORCE_COLOR` handling
- Command help with `php run help `
- Built-in `commands` command for shell autocomplete
- `--key=value` options (repeatable) and boolean `--flag` / `-h` flags; `--` ends option parsing
- Io helpers for output: `info()`, `success()`, `warn()`, `error()`, `echoln()` (warnings and errors go to STDERR)
- Inline markup for styled output: ``, ``, ``, ``, the ANSI colors — ``, ``, ``, ... — and truecolor hex tags: ``, ``
- Interactive prompts: `ask()` (optionally with hidden input), `confirm()`, and `choice()`
- `BufferedIo` for testing commands without output buffering or escape-code stripping
- Text formatting helpers: `indent()` wraps, `pad()` aligns, `rule()` separates — all on the visible width, markup and multibyte aware
- `Table` for minimal scc-style column output — no borders, no cell wrapping
- Debug mode for detailed error traces

Installation
------------

[](#installation)

```
composer require celema/console
```

Quick Start
-----------

[](#quick-start)

A command is a plain invokable class with a `#[Command]` attribute:

```
use Celema\Console\{Arg, Args, Command, Opt, Io};

#[Command('grp:mycommand', 'This is my command')]
#[Arg('name', 'Who to greet', optional: true)]
#[Opt('--force', 'Skip the safety net')]
class MyCommand
{
    public function __invoke(Args $args, Io $io): int
    {
        $name = $args->positional(0, 'world');
        $io->info("Running my command for {$name}");
        $io->success('Command completed!');

        return 0;
    }
}
```

`__invoke()` must declare the return type `int` (the exit code). Its `Args` and `Io` parameters are matched by type, not position: each is optional and their order is free, but no other parameters are allowed.

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()`:

```