Need help with php-cli?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

194 Stars 19 Forks MIT License 386 Commits 3 Opened issues


PHP Console Application made easy- build great console apps with ease. Comes with Zero Dependency and Autocompletion support.

Services available


Need anything else?

Contributors list

# 160,720
282 commits
# 369,237
44 commits
# 429,778
6 commits
# 632,280
5 commits
# 726,677
2 commits


Framework agnostic Command Line Interface utilities and helpers for PHP. Build Console App with ease, fun and love.

Latest Version Travis Build Scrutinizer CI Codecov branch StyleCI Software License Donate 15 Donate 25 Donate 50 Tweet

  • Command line application made easy
  • Inspired by nodejs commander (thanks tj)
  • Zero dependency.
  • For PHP7 and for good

Screen Preview

What's included

Core: Argv parser · Cli application · Shell

IO: Colorizer · Cursor manipulator · Stream writer · Stream reader

Other: Autocompletion


composer require adhocore/cli


Argv parser

$command = new Ahc\Cli\Input\Command('rmdir', 'Remove dirs');

$command ->version('0.0.1-dev') // Arguments are separated by space // Format: <name> for required, [name] for optional // [name:default] for default value, [name...] for variadic (last argument) ->arguments('

[dirs...]') // -h --help, -V --version, -v --verbosity options are already added by default. // Format: <name> for required, [name] for optional ->option('-s --with-subdir', 'Also delete subdirs (with means false by default)') ->option('-e,--no-empty', 'Delete empty (no means true by default)') // Specify santitizer/callback as 3rd param, default value as 4th param ->option('-d|--depth [nestlevel]', 'How deep to process subdirs', 'intval', 5) ->parse(['thisfile.php', '-sev', 'dir', 'dir1', 'dir2', '-vv']) // $_SERVER['argv'] ;

// Print all values: print_r($command->values());

/*Array ( [help] => [version] => 0.0.1 [verbosity] => 3 [dir] => dir [dirs] => Array ( [0] => dir1 [1] => dir2 )

[subdir] =&gt; true
[empty] =&gt; false
[depth] =&gt; 5


// To get values for options except the default ones (help, version, verbosity) print_r($command->values(false));

// Pick a value by name $command->dir; // dir $command->dirs; // [dir1, dir2] $command->depth; // 5

Command help

It can be triggered manually with

or automatic when
option is passed to

For above example, the output would be: Command Help

Command version

It can be triggered manually with

or automatic when
option is passed to

For above example, the output would be:


Console app

Definitely check adhocore/phint - a real world console application made using


Here we simulate a

app with limited functionality of
, and
. You will see how intuitive, fluent and cheese building a console app is!

Git app

$app = new Ahc\Cli\Application('git', '0.0.1');

$app // Register add command ->command('add', 'Stage changed files', 'a') // alias a // Set options and arguments for this command ->arguments(' [paths...]') ->option('-f --force', 'Force add ignored file', 'boolval', false) ->option('-N --intent-to-add', 'Add content later but index now', 'boolval', false) // Handler for this command: param names should match but order can be anything :) ->action(function ($path, $paths, $force, $intentToAdd) { array_unshift($paths, $path);

        echo ($intentToAdd ? 'Intent to add ' : 'Add ')
            . implode(', ', $paths)
            . ($force ? ' with force' : '');

        // If you return integer from here, that will be taken as exit error code
    // Done setting up this command for now, tap() to retreat back so we can add another command
-&gt;command('checkout', 'Switch branches', 'co') // alias co
    -&gt;option('-b --new-branch', 'Create a new branch and switch to it', false)
    -&gt;option('-f --force', 'Checkout even if index differs', 'boolval', false)
    -&gt;action(function ($branch, $newBranch, $force) {
        echo 'Checkout to '
            . ($newBranch ? 'new ' . $branch : $branch)
            . ($force ? ' with force' : '');


// Parse only parses input but doesnt invoke action $app->parse(['git', 'add', 'path1', 'path2', 'path3', '-f']);

// Handle will do both parse and invoke action. $app->handle(['git', 'add', 'path1', 'path2', 'path3', '-f']); // Will produce: Add path1, path2, path3 with force

$app->handle(['git', 'co', '-b', 'master-2', '-f']); // Will produce: Checkout to new master-2 with force

Organized app

Instead of inline commands/actions, we define and add our own commands (having

) to the app:
class InitCommand extends Ahc\Cli\Input\Command
    public function __construct()
        parent::__construct('init', 'Init something');

        -&gt;argument('<arrg>', 'The Arrg')
        -&gt;argument('[arg2]', 'The Arg2')
        -&gt;option('-a --apple', 'The Apple')
        -&gt;option('-b --ball', 'The ball')
        // Usage examples:
            // append details or explanation of given example with ` ## ` so they will be uniformly aligned when shown
            '<bold>  init <comment>--apple applet --ball ballon <arggg> ## details 1<eol></eol>' .
            // $0 will be interpolated to actual command name
            '<bold>  $0 <comment>-a applet -b ballon <arggg> [arg2] ## details 2<eol></eol>'

// This method is auto called before `self::execute()` and receives `Interactor $io` instance
public function interact(Ahc\Cli\IO\Interactor $io)
    // Collect missing opts/args
    if (!$this-&gt;apple) {
        $this-&gt;set('apple', $io-&gt;prompt('Enter apple'));

    if (!$this-&gt;ball) {
        $this-&gt;set('ball', $io-&gt;prompt('Enter ball'));

    // ...

// When app-&gt;handle() locates `init` command it automatically calls `execute()`
// with correct $ball and $apple values
public function execute($ball, $apple)
    $io = $this-&gt;app()-&gt;io();

    $io-&gt;write('Apple ' . $apple, true);
    $io-&gt;write('Ball ' . $ball, true);

    // more codes ...

    // If you return integer from here, that will be taken as exit error code


class OtherCommand extends Ahc\Cli\Input\Command { // ... }

// Init App with name and version $app = new Ahc\Cli\Application('App', 'v0.0.1');

// Add commands with optional aliases` $app->add(new InitCommand, 'i'); $app->add(new OtherCommand, 'o');

// Set logo $app->logo('Ascii art logo of your app');

$app->handle($_SERVER['argv']); // if argv[1] is i or init it executes InitCommand

App help

It can be triggered manually with

or automatic when
option is passed to
. Note If you pass something like
['app', cmd', '-h']
it will automatically and instantly show you help of that
and not the

For above example, the output would be: App Help

App version

Same version number is passed to all attached Commands. So you can trigger version on any of the commands.


Very thin shell wrapper that provides convenience methods around


Basic usage

$shell = new Ahc\Cli\Helper\Shell($command = 'php -v', $rawInput = null);

// Waits until proc finishes $shell->execute($async = false); // default false

echo $shell->getOutput(); // PHP version string (often with zend/opcache info)

Advanced usage

$shell = new Ahc\Cli\Helper\Shell('php /some/long/running/scipt.php');

// With async flag, doesnt wait for proc to finish! $shell->setOptions($workDir = '/home', $envVars = []) ->execute($async = true) ->isRunning(); // true

// Force stop anytime (please check $shell->stop(); // also closes pipes

// Force kill anytime (please check $shell->kill();


$shell = new Ahc\Cli\Helper\Shell('php /some/long/running/scipt.php');

// Wait for at most 10.5 seconds for proc to finish! // If it doesnt complete by then, throws exception $shell->setOptions($workDir, $envVars, $timeout = 10.5)->execute();

// And if it completes within timeout, you can access the stdout/stderr echo $shell->getOutput(); echo $shell->getErrorOutput();

Cli Interaction

You can perform user interaction like printing colored output, reading user input programatically and moving the cursors around with provided

$interactor = new Ahc\Cli\IO\Interactor;

// For mocking io: $interactor = new Ahc\Cli\IO\Interactor($inputPath, $outputPath);


$confirm = $interactor->confirm('Are you happy?', 'n'); // Default: n (no)
$confirm // is a boolean
    ? $interactor->greenBold('You are happy :)', true)  // Output green bold text
    : $interactor->redBold('You are sad :(', true);     // Output red bold text

Single choice

$fruits = ['a' => 'apple', 'b' => 'banana'];
$choice = $interactor->choice('Select a fruit', $fruits, 'b');
$interactor->greenBold("You selected: {$fruits[$choice]}", true);

Multiple choices

$fruits  = ['a' => 'apple', 'b' => 'banana', 'c' => 'cherry'];
$choices = $interactor->choices('Select fruit(s)', $fruits, ['b', 'c']);
$choices = \array_map(function ($c) use ($fruits) { return $fruits[$c]; }, $choices);
$interactor->greenBold('You selected: ' . implode(', ', $choices), true);

Prompt free input

$any = $interactor->prompt('Anything', rand(1, 100)); // Random default
$interactor->greenBold("Anything is: $any", true);

Prompt with validation

$nameValidator = function ($value) {
    if (\strlen($value) < 5) {
        throw new \InvalidArgumentException('Name should be atleast 5 chars');

return $value;


// No default, Retry 5 more times $name = $interactor->prompt('Name', null, $nameValidator, 5); $interactor->greenBold("The name is: $name", true);

Prompt hidden

On windows platform, it may change the fontface which can be fixed.

$passValidator = function ($pass) {
    if (\strlen($pass) < 6) {
        throw new \InvalidArgumentException('Password too short');

return $pass;


$pass = $interactor->promptHidden('Password', $passValidator, 2);

Interactive Preview

IO Components

The interactor is composed of

while the
itself is composed of
. All these components can be used standalone.


Color looks cool!

$color = new Ahc\Cli\Output\Color;

Simple usage

echo $color->warn('This is warning');
echo $color->info('This is info');
echo $color->error('This is error');
echo $color->comment('This is comment');
echo $color->ok('This is ok msg');

Custom style

Ahc\Cli\Output\Color::style('mystyle', [
    'bg' => Ahc\Cli\Output\Color::CYAN,
    'fg' => Ahc\Cli\Output\Color::WHITE,
    'bold' => 1, // You can experiment with 0, 1, 2, 3 ... as well

echo $color->mystyle('My text');


Move cursor around, erase line up or down, clear screen.

$cursor = new Ahc\Cli\Output\Cursor;

echo $cursor->up(1) . $cursor->down(2) . $cursor->right(3) . $cursor->left(4) . $cursor->next(0) . $cursor->prev(2); . $cursor->eraseLine() . $cursor->clear() . $cursor->clearUp() . $cursor->clearDown() . $cursor->moveTo(5, 8); // x, y


Write anything in style.

$writer = new Ahc\Cli\Output\Writer;

// All writes are forwarded to STDOUT // But if you specify error, then to STDERR $writer->errorBold('This is error');

Output formatting

You can call methods composed of any combinations:

'', 'bold', 'bg', 'fg', 'warn', 'info', 'error', 'ok', 'comment'
... in any order (eg:
and so on ...)
$writer->bold->green->write('It is bold green');
$writer->boldGreen('It is bold green'); // Same as above
$writer->comment('This is grayish comment', true); // True indicates append EOL character.
$writer->bgPurpleBold('This is white on purple background');

Free style

Many colors with one single call: wrap text with tags


For NL/EOL just use 

Great for writing long colorful texts for example command usage info.

$writer->colors('This is redThis has bg Green');

Raw output

$writer->raw('Enter name: ');


Just pass array of assoc arrays. The keys of first array will be taken as heading. Heading is auto inflected to human readable capitalized words (ucwords).

    ['a' => 'apple', 'b-c' => 'ball', 'c_d' => 'cat'],
    ['a' => 'applet', 'b-c' => 'bee', 'c_d' => 'cute'],

Gives something like:

| A      | B C  | C D  |
| apple  | ball | cat  |
| applet | bee  | cute |

Designing table look and feel

Just pass 2nd param

    ['a' => 'apple', 'b-c' => 'ball', 'c_d' => 'cat'],
    ['a' => 'applet', 'b-c' => 'bee', 'c_d' => 'cute'],
], [
    // for => styleName (anything that you would call in $writer instance)
    'head' => 'boldGreen', // For the table heading
    'odd'  => 'bold',      // For the odd rows (1st row is odd, then 3, 5 etc)
    'even' => 'comment',   // For the even rows (2nd row is even, then 4, 6 etc)

// 'head', 'odd', 'even' are all the styles for now // In future we may support styling a column by its name!


Read and pre process user input.

$reader = new Ahc\Cli\Input\Reader;

// No default, callback fn ucwords() $reader->read(null, 'ucwords');

// Default 'abc', callback trim() $reader->read('abc', 'trim');

// Read at most first 5 chars // (if ENTER is pressed before 5 chars then further read is aborted) $reader->read('', 'trim', 5);

// Read but dont echo back the input $reader->readHidden($default, $callback);

// Read from piped stream (or STDIN) if available without waiting $reader->readPiped();

// Pass in a callback for if STDIN is empty // The callback recieves $reader instance and MUST return string $reader->readPiped(function ($reader) { // Wait to read a line! return $reader->read();

// Wait to read multi lines (until Ctrl+D pressed)
return $reader-&gt;readAll();



Whenever an exception is caught by

, it will show a beautiful stack trace and exit with non 0 status code.

Exception Preview


Any console applications that are built on top of adhocore/cli can entertain autocomplete of commands and options in zsh shell with oh-my-zsh.

All you have to do is add one line to the end of


compdef _ahccli 


compdef _ahccli phint
for phint.

That is cumbersome to perform manually, here's a complete command you can copy/paste/run:

One time setup

mkdir -p ~/.oh-my-zsh/custom/plugins/ahccli && cd ~/.oh-my-zsh/custom/plugins/ahccli

[ -f ./ahccli.plugin.zsh ] || curl -sSLo ./ahccli.plugin.zsh

chmod 760 ./ahccli.plugin.zsh && cd -

Load ahccli plugin

This is also one time setup.

# Open .zshrc
nano ~/.zshrc

locate plugins=(... ...) and add ahccli

plugins=(git ... ... ahccli)

... then save it (Ctrl + O)

Registering app

# replace appname with real name eg: phint
echo compdef _ahccli appname >> ~/.oh-my-zsh/custom/plugins/ahccli/ahccli.plugin.zsh

Of course you can add multiple apps, just change appname in above command

Then either restart the shell or source the plugin like so:

source ~/.oh-my-zsh/custom/plugins/ahccli/ahccli.plugin.zsh

Trigger autocomplete

appname             # autocompletes commands               (phint )
appname subcommand  # autocompletes options for subcommand (phint init )




© 2017-2020, Jitendra Adhikari | MIT


This project is release managed by please.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.