Command-Line Interface tools

Last update: May 6, 2022

Aura.Cli

Provides the equivalent of request ( Context ) and response ( Stdio ) objects for the command line interface, including Getopt support, and an independent Help object for describing commands.

Foreword

Installation

This library requires PHP 5.3 or later; we recommend using the latest available version of PHP as a matter of principle. It has no userland dependencies.

It is installable and autoloadable via Composer as aura/cli.

Alternatively, download a release or clone this repository, then require or include its autoload.php file.

Quality

Scrutinizer Code Quality Code Coverage Build Status

To run the unit tests at the command line, issue composer install and then phpunit at the package root. This requires Composer to be available as composer, and PHPUnit to be available as phpunit.

This library attempts to comply with PSR-1, PSR-2, and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Community

To ask questions, provide feedback, or otherwise communicate with the Aura community, please join our Google Group, follow @auraphp on Twitter, or chat with us on #auraphp on Freenode.

Getting Started

Context Discovery

The Context object provides information about the command line environment, including any option flags passed via the command line. (This is the command line equivalent of a web request object.)

Instantiate a Context object using the CliFactory; pass it a copy of $GLOBALS.

<?php
use Aura\Cli\CliFactory;

$cli_factory = new CliFactory;
$context = $cli_factory->newContext($GLOBALS);
?>

You can access the $_ENV, $_SERVER, and $argv values with the $env, $server, and $argv property objects, respectively. (Note that these properties are copies of those superglobals as they were at the time of Context instantiation.) You can pass an alternative default value if the related key is missing.

<?php
// get copies of superglobals
$env    = $context->env->get();
$server = $context->server->get();
$argv   = $context->argv->get();

// equivalent to:
// $value = isset($_ENV['key']) ? $_ENV['key'] : null;
$value = $context->env->get('key');

// equivalent to:
// $value = isset($_ENV['key']) ? $_ENV['key'] : 'other_value';
$value = $context->env->get('key', 'other_value');
?>

Getopt Support

The Context object provides support for retrieving command-line options and params, along with positional arguments.

To retrieve options and arguments parsed from the command-line $argv values, use the getopt() method on the Context object. This will return a GetoptValues object for you to use as as you wish.

Defining Options and Params

To tell getopt() how to recognize command line options, pass an array of option definitions. The definitions array format is similar to, but not exactly the same as, the one used by the getopt() function in PHP. Instead of defining short flags in a string and long options in a separate array, they are both defined as elements in a single array. Adding a * after the option name indicates it can be passed multiple times; its values will be stored in an array.

<?php
$options = array(
    'a',        // short flag -a, parameter is not allowed
    'b:',       // short flag -b, parameter is required
    'c::',      // short flag -c, parameter is optional
    'foo',      // long option --foo, parameter is not allowed
    'bar:',     // long option --bar, parameter is required
    'baz::',    // long option --baz, parameter is optional
    'g*::',     // short flag -g, parameter is optional, multi-pass
);

$getopt = $context->getopt($options);
?>

N.b.: When we say "required" here, it means "the option, when present, must have a parameter." It does not mean "the option must be present." These are options, after all. If a particular value must be passed, consider using positional arguments instead.

Use the get() method on the returned GetoptValues object to retrieve the option values. You can provide an alternative default value for when the option is missing.

<?php
$a   = $getopt->get('-a', false); // true if -a was passed, false if not
$b   = $getopt->get('-b');
$c   = $getopt->get('-c', 'default value');
$foo = $getopt->get('--foo', 0); // true if --foo was passed, false if not
$bar = $getopt->get('--bar');
$baz = $getopt->get('--baz', 'default value');
$g   = $getopt->get('-g', []);
?>

If you want to alias one option name to another, comma-separate the two names. The values will be stored under both names;

<?php
// alias -f to --foo
$options = array(
    'foo,f:',  // long option --foo or short flag -f, parameter required
);

$getopt = $context->getopt($options);

$foo = $getopt->get('--foo'); // both -f and --foo have the same values
$f   = $getopt->get('-f'); // both -f and --foo have the same values
?>

If you want to allow an option to be passed multiple times, add a '*' to the end of the option name.

<?php
$options = array(
    'f*',
    'foo*:'
);

$getopt = $context->getopt($options);

// if the script was invoked with:
// php script.php --foo=foo --foo=bar --foo=baz -f -f -f
$foo = $getopt->get('--foo'); // ['foo', 'bar', 'baz']
$f   = $getopt->get('-f'); // [true, true, true]
?>

If the user passes options that do not conform to the definitions, the GetoptValues object retains various errors related to the parsing failures. In these cases, hasErrors() will return true, and you can then review the errors. (The errors are actually Aura\Cli\Exception objects, but they don't get thrown as they occur; this is so that you can deal with or ignore the different kinds of errors as you like.)

<?php
$getopt = $context->getopt($options);
if ($getopt->hasErrors()) {
    $errors = $getopt->getErrors();
    foreach ($errors as $error) {
        // print error messages to stderr using a Stdio object
        $stdio->errln($error->getMessage());
    }
};
?>

Positional Arguments

To get the positional arguments passed to the command line, use the get() method and the argument position number:

<?php
$getopt = $context->getopt($options);

// if the script was invoked with:
// php script.php arg1 arg2 arg3 arg4

$val0 = $getopt->get(0); // script.php
$val1 = $getopt->get(1); // arg1
$val2 = $getopt->get(2); // arg2
$val3 = $getopt->get(3); // arg3
$val4 = $getopt->get(4); // arg4
?>

Defined options will be removed from the arguments automatically.

<?php
$options = array(
    'a',
    'foo:',
);

$getopt = $context->getopt($options);

// if the script was invoked with:
// php script.php arg1 --foo=bar -a arg2
$arg0 = $getopt->get(0); // script.php
$arg1 = $getopt->get(1); // arg1
$arg2 = $getopt->get(2); // arg2
$foo  = $getopt->get('--foo'); // bar
$a    = $getopt->get('-a'); // 1
?>

N.b.: If a short flag has an optional parameter, the argument immediately after it will be treated as the option value, not as an argument.

Standard Input/Output Streams

The Stdio object allows you to work with standard input/output streams. (This is the command line equivalent of a web response object.)

Instantiate a Stdio object using the CliFactory.

<?php
use Aura\Cli\CliFactory;

$cli_factory = new CliFactory;
$stdio = $cli_factory->newStdio();
?>

It defaults to using php://stdin, php://stdout, and php://stderr, but you can pass whatever stream names you like as parameters to the newStdio() method.

The Stdio object methods are ...

  • getStdin(), getStdout(), and getStderr() to return the respective Handle objects;

  • outln() and out() to print to stdout, with or without a line ending;

  • errln() and err() to print to stderr, with or without a line ending;

  • inln() and in() to read from stdin until the user hits enter; inln() leaves the trailing line ending in place, whereas in() strips it.

You can use special formatting markup in the output and error strings to set text color, text weight, background color, and other display characteristics. See the formatter cheat sheet below.

<?php
// print to stdout
$stdio->outln('This is normal text.');

// print to stderr
$stdio->errln('<<red>>This is an error in red.');
$stdio->errln('Output will stay red until a formatting change.<<reset>>');
?>

Exit Codes

This library comes with a Status class that defines constants for exit status codes. You should use these whenever possible. For example, if a command is used with the wrong number of arguments or improper option flags, exit() with Status::USAGE. The exit status codes are the same as those found in sysexits.h.

Writing Commands

The Aura.Cli library does not come with an abstract or base command class to extend from, but writing commands for yourself is straightforward. The following is a standalone command script, but similar logic can be used in a class. Save it in a file named hello and invoke it with php hello [-v,--verbose] [name].

<?php
use Aura\Cli\CliFactory;
use Aura\Cli\Status;

require '/path/to/Aura.Cli/autoload.php';

// get the context and stdio objects
$cli_factory = new CliFactory;
$context = $cli_factory->newContext($GLOBALS);
$stdio = $cli_factory->newStdio();

// define options and named arguments through getopt
$options = ['verbose,v'];
$getopt = $context->getopt($options);

// do we have a name to say hello to?
$name = $getopt->get(1);
if (! $name) {
    // print an error
    $stdio->errln("Please give a name to say hello to.");
    exit(Status::USAGE);
}

// say hello
if ($getopt->get('--verbose')) {
    // verbose output
    $stdio->outln("Hello {$name}, it's nice to see you!");
} else {
    // plain output
    $stdio->outln("Hello {$name}!");
}

// done!
exit(Status::SUCCESS);
?>

Writing Command Help

Sometimes it will be useful to provide help output for your commands. With Aura.Cli, the Help object is separate from any command you may write. It may be manipulated externally or extended.

For example, extend the Help object and override the init() method.

<?php
use Aura\Cli\Help;

class MyCommandHelp extends Help
{
    protected function init()
    {
        $this->setSummary('A single-line summary.');
        $this->setUsage('<arg1> [<arg2>]');
        $this->setOptions(array(
            'f,foo' => "The -f/--foo option description.",
            'bar::' => "The --bar option description.",
        ));
        $this->setDescr("A multi-line description of the command.");
    }
}
?>

Then instantiate the new class and pass its getHelp() output through Stdio:

<?php
use Aura\Cli\CliFactory;
use Aura\Cli\Context\OptionFactory;

$cli_factory = new CliFactory;
$stdio = $cli_factory->newStdio();

$help = new MyCommandHelp(new OptionFactory);
$stdio->outln($help->getHelp('my-command'));
?>
  • We keep the command name itself outside of the help class, because the command name may be mapped differently in different projects.

  • We pass a GetoptParser to the Help object so it can parse the option definitions.

  • We can get the option definitions out of the Help object using getOptions(); this allows us to pass a Help object into a hypothetical command object and reuse the definitions.

The output will look something like this:

SUMMARY
    my-command -- A single-line summary.

USAGE
    my-command <arg1> [<arg2>]

DESCRIPTION
    A multi-line description of the command.

OPTIONS
    -f
    --foo
        The -f/--foo option description.

    --bar[=<value>]
        The --bar option description.

As a side note, the array of options passed to setOptions() may contain argument descriptions as well. These are in the format #argname (to indicate a required argument) and #argname? (to indicate an optional argument). They may additionally be used as keys, with corresponding description values. Their presence in a Getopt definition array is ignored, but the Help object will read them and generate output for them automatically.

For example, the following code (notice the lack of a setUsage() call)...

<?php
use Aura\Cli\CliFactory;
use Aura\Cli\Context\OptionFactory;
use Aura\Cli\Help;

$cli_factory = new CliFactory;
$stdio = $cli_factory->newStdio();

$help = new Help(new OptionFactory);
$this->setSummary('A single-line summary.');
$help->setOptions(array(
    'f,foo' => "The -f/--foo option description.",
    'bar::' => "The --bar option description.",
    '#arg1' => "The description for argument 1.",
    '#arg2?' => "The description for argument 2.",
));
$this->setDescr("A multi-line description of the command.");

$stdio->outln($help->getHelp('my-command'));
?>

... will generate the following output:

SUMMARY
    my-command -- A single-line summary.

USAGE
    my-command <arg1> [<arg2>]

DESCRIPTION
    A multi-line description of the command.

ARGUMENTS
    <foo>
        The description for argument 1.

    <bar>
        The description for argument 2.

OPTIONS
    -f
    --foo
        The -f/--foo option description.

    --bar[=<value>]
        The --bar option description.

Formatter Cheat Sheet

On POSIX terminals, <<markup>> strings will change the display characteristics. Note that these are not HTML tags; they will be converted into terminal control codes, and do not get "closed". You can place as many space-separated markup codes between the double angle-brackets as you like.

reset       reset display to defaults

black       black text
red         red text
green       green text
yellow      yellow text
blue        blue text
magenta     magenta (purple) text
cyan        cyan (light blue) text
white       white text

blackbg     black background
redbg       red background
greenbg     green background
yellowbg    yellow background
bluebg      blue background
magentabg   magenta (purple) background
cyanbg      cyan (light blue) background
whitebg     white background

bold        bold in the current text and background colors
dim         dim in the current text and background colors
ul          underline in the current text and background colors
blink       blinking in the current text and background colors
reverse     reverse the current text and background colors

For example, to set bold white text on a red background, add <<bold white redbg>> into your output or error string. Reset back to normal with <<reset>>.

GitHub

https://github.com/auraphp/Aura.Cli
Comments
  • 1. Updated AbstractCommand::catchException() when re-throwing the exception...

    ... to cast the exception's code to an int

    Find it the hard way when creating a Cli App using PDO. The Pdo was throwing an exception with code HY093 - which is not numeric. So... just in case :-)

    Reviewed by gpapadopg at 2012-12-05 09:05
  • 2. Positional argument help text

    It would be nice to have an Aura\Cli\Help::getHelpArguments() formatting function in the same vein as the others, but used for describing the positional arguments. (feature request)

    Reviewed by cxj at 2014-10-31 19:53
  • 3. Slight Help text reformatting -- minor feature request

    From the "it would be nice" department...

    I'd like the OPTIONS sections formatted like this:

        -f, --foo=<value>
    

    instead of the current:

        -f <value>
        --foo=<value>
    

    It strikes me as peculiar that I can pass a value as:

    mycommand -f 99
    mycommand --foo=99
    

    But not as:

    mycommand --foo 99
    

    At least, according to the help text.

    And I really ought to go figure out how to write PhpUnit tests, so that I can start sending pull requests. I'm using PhpSpec for my own code.

    Reviewed by cxj at 2015-03-24 21:05
  • 4. getOpt->getOptions() is not accessible

    In 7fff85abc5 you moved getOptions() from GetOpt to GetOptParser

    This change broke our custom build help system. (which we made before you added https://github.com/auraphp/Aura.Cli/blob/develop-2/src/Help.php).

    The primary problem is that we used $getopt->getOptions() and then looped over the options and outputted our own pretty-formatted help. As far as I am aware, there is now no way to access the getOptions() call, which has moved to GetOptParser.

    Is there a way we can access GetOptParser->getOptions() ?

    Reviewed by bluehawk at 2014-05-07 18:43
  • 5. Context object unreliable

    Using the example from the Aura.Cli README.md, I tried to retrieve the value of an environment variable. It failed. Upon debugging, I found that the $_ENV super global was empty. The reason was because my laptop and my employer's servers all have

    variables_order = "GPCS"
    

    in the lynx.ini files. That is to say, $_ENV super global and its equivalents never get set without the "E": http://php.net/manual/en/reserved.variables.environment.php#98113

    This is apparently a common configuration these days.

    Strangely, the environment variables were all imported into the $_SERVER super global. This is documented as being true whenever "S" is specified for the CGI and FastCGI SAPIs, but no mention of the CLI SAPI is made: http://us.php.net/manual/en/ini.core.php#ini.variables-order

    The only reliable way to get environment variables seems to be getenv().

    This is really a PHP problem, and probably a result of the CLI SAPI being a "poor stepchild" in PHP for so long. But it seems like Aura.Cli should do its best to try to work around it. A CLI program with environment variables is like a web application without a Document Root.

    I'd provide pull requests for potential patches except at the moment, I'm not sure what the cleanest way to fix this is.

    Reviewed by cxj at 2014-10-31 14:26
  • 6. Add test for concatenated short options with an optional argument.

    I believe this test is sufficient for making this feature work, but there might be some edge cases which would warrant more tests for really complete code coverage and regression testing. They might include the following:

    1. Test for an intentional failure of a required argument.
    2. Test for success with absent optional argument.

    Partial solution for issue #58.

    Reviewed by cxj at 2017-08-09 20:48
  • 7. Add support for spaces as separator between longopt and their values

    This PR adds the ability to use spaces between longopts and their values following the same way as PHP's built-in getopt function.

    see: http://php.net/manual/en/function.getopt.php

    Reviewed by jclaveau at 2016-01-05 11:43
  • 8. Required params non-setted, not present

    Hello, when we have required parameters that where not setted, the systems don't make any error. It should provide any error on hasError ...

    Example :

    $options = array(
        'action,a:',
        'module,m:'
    );
    $getOpt = $context->getopt($options);
    
    // check errors
    if ($getOpt->hasErrors())
    {
        foreach ($getOpt->getErrors() as $error)
        {
            $stdio->errln($error->getMessage());
        }
        exit(Status::USAGE);
    }
    

    when I try this with php cli.php -a test I have no error ....

    tested on php 5.3

    Reviewed by Grummfy at 2013-12-01 21:50
  • 9. Colors broken

    A recent change broke the color rendering in Aura for us.

    Our setup is that we are using PuTTY to SSH into a Gentoo server, not sure if that's relevant. The problem is present in both PHP version PHP 5.3.28-pl1-gentoo (cli) (built: Mar 10 2014 18:34:15) and PHP 5.4.23-pl0-gentoo (cli) (built: Mar 10 2014 18:17:14)

    I did a bisect, and the offending commit seems to be:

    ddcb86be93c9b8ed6991fe98a9d5733970a58399 is the first bad commit
    commit ddcb86be93c9b8ed6991fe98a9d5733970a58399
    Author: Paul M. Jones <[email protected]>
    Date:   Tue Apr 15 20:42:39 2014 -0500
    
        soothe the scrutinizer
    

    Here are some screenshots that show this:

    (./minion is an executable script we created to run cli commands using Aura)

    image

    image

    image

    image

    It seems that casting the file descriptor to an int is somehow making Aura think it isn't a TTY anymore. I'm not really sure why that happens, since the php docs say that you should pass in an int.

    What was the context for casting it to an int in order to "soothe the scrutinizer"? If casting to an int is necessary for scrutinizer to pass, the following line could be a solution:

     $this->posix = posix_isatty($this->resource) OR posix_isatty((int) $this->resource);
    
    Reviewed by bluehawk at 2014-04-22 15:34
  • 10. test needs the framework to run

    This test here is a bit misleading because it assumes we are using the framework, https://github.com/auraphp/Aura.Cli/blob/develop-2/tests/config/DefaultTest.php#L4 could it be that we can move this to the respective glue package?

    Reviewed by cordoval at 2014-02-07 21:45
  • 11. Options "nesting"

    Hi again

    If you "nest" options within other options this leads to problems.

    Example: --option="sometext -parameter"

    Parameter now will be recognized as an Aura option.

    In my use case I need to enter shell commands like hostname -f - thus, this will fail.

    Therefor text entered between "" entered right after an option should be ignored.

    Reviewed by michelkaeser at 2013-07-21 23:16
  • 12. Feature request: allow appending additional sections to output

    I can obviously extend class Help and override method getHelp() to create a class of my own which does the following, but would you consider incorporating it into Aura.Cli itself? If so, I'll provide a PR.

    I'd like to be able to append additional "sections" of output to what's returned by getHelp(), so that they would appear after the OPTIONS section. For example (via some quick hacking), an EXAMPLES section:

    OPTIONS
        -v
        --verbose
            Verbose output.
    
        -h
        --help
            This help.
    
        -c [<value>]
            Config file directory (default: ./conf).
    
    EXAMPLES
        generate build -v
    
    Reviewed by cxj at 2017-08-08 18:55
  • 13. Does not handle Unix convention of concatenated options

    Context::getopt() (probably) doesn't allow for the Unix convention of shortening options by concatenating them. Example:

    896 pds/skeleton$ tar -c -v -f foo.tar src/
    a src
    a src/ComplianceValidator.php
    a src/Console.php
    a src/PackageGenerator.php
    a src/TestRunner.php
    
    
    897 pds/skeleton$ tar -cvf foo.tar
    src/
    src/ComplianceValidator.php
    src/Console.php
    src/PackageGenerator.php
    src/TestRunner.php
    

    Note how first call to tar uses separated arguments -c -v and -f foo.tar, compared to second call where -cvf are concatenated. Most *nix commands follow this convention.

    However when using Aura.Cli with the latter (concatenated) case, $getopt->get('-f') returns 1 instead of foo.tar.

    Reviewed by cxj at 2017-08-08 18:41
Skeleton for creating a new Command Line Interface application with a minimum of dependencies.

Skeleton for creating a new Command Line Interface application with a minimum of dependencies.

Jan 17, 2022
Provides the equivalent of request ( Context ) and response ( Stdio ) objects for the command line interface

Provides the equivalent of request ( Context ) and response ( Stdio ) objects for the command line interface, including Getopt support, and an independent Help object for describing commands.

May 6, 2022
The Platform.sh CLI is the official command-line interface for Platform.sh

The Platform.sh CLI is the official command-line interface for Platform.sh. Use this tool to interact with your Platform.sh projects, and to build them locally for development purposes.

May 17, 2022
Lovely PHP wrapper for using the command-line

ShellWrap What is it? It's a beautiful way to use powerful Linux/Unix tools in PHP. Easily and logically pipe commands together, capture errors as PHP

May 3, 2022
A PHP library for command-line argument processing

GetOpt.PHP GetOpt.PHP is a library for command-line argument processing. It supports PHP version 5.4 and above. Releases For an overview of the releas

May 24, 2022
Another Command Line Argument Parser

Optparse — Another Command Line Argument Parser Install 1. Get composer. 2. Put this into your local composer.json: { "require": { "chh/optparse

Nov 1, 2019
👨🏻‍🚀 A command-line tool that gives you the Alpine Day 2021 schedule in your timezone. 🚀
👨🏻‍🚀 A command-line tool that gives you the Alpine Day 2021 schedule in your timezone. 🚀

Alpine Day Schedule a command-line tool that gives you the Alpine Day 2021 schedule in your timezone. ?? Quick start Requires PHP 7.4+ # First, instal

Jun 10, 2021
PHP Interminal is a command-line tool that gives you access to PHP Internals discussions in your terminal.
PHP Interminal is a command-line tool that gives you access to PHP Internals discussions in your terminal.

PHP Interminal is a command-line tool that gives you access to PHP Internals discussions in your terminal. ??

Dec 12, 2021
Patrol is an elegant command-line tool that keeps your PHP Project's dependencies in check.
Patrol is an elegant command-line tool that keeps your PHP Project's dependencies in check.

Patrol is an elegant command-line tool that keeps your PHP Project's dependencies in check. Installation / Usage Requires PHP 8.0+ First, install Patr

May 27, 2022
Twitter raffles in the command line, with PHP and minicli
Twitter raffles in the command line, with PHP and minicli

Rafflebird Rafflebird is a highly experimental CLI application for giveaways / raffles on Twitter, built in PHP with Minicli. Disclaimer: The recent s

May 14, 2022
A command line code generator for Drupal.

Drupal Code Generator A command line code generator for Drupal. Installation Download the latest stable release of the code generator.

May 20, 2022
A PHP command line tool used to install shlink
A PHP command line tool used to install shlink

Shlink installer A PHP command line tool used to install shlink. Installation Install this tool using composer.

Jan 10, 2022
Laracon Schedule a command-line tool that gives you the Laracon Online schedule in your timezone.
Laracon Schedule a command-line tool that gives you the Laracon Online schedule in your timezone.

Laracon Schedule a command-line tool that gives you the Laracon Online schedule in your timezone. ?? Quick start Requires PHP 7.4+ # First, install: c

Dec 13, 2021
Command-line control panel for Nginx Server to manage WordPress sites running on Nginx, PHP, MySQL, and Let's Encrypt
Command-line control panel for Nginx Server to manage WordPress sites running on Nginx, PHP, MySQL, and Let's Encrypt

EasyEngine v4 EasyEngine makes it greatly easy to manage nginx, a fast web-server software that consumes little memory when handling increasing volume

May 22, 2022
Generic PHP command line flags parse library
Generic PHP command line flags parse library

PHP Flag Generic PHP command line flags parse library Features Generic CLI options and arguments parser. Support set value data type(int,string,bool,a

Mar 2, 2022
A simple command-line tool whose aim is to facilitate the continous delivery of PHP apps
A simple command-line tool whose aim is to facilitate the continous delivery of PHP apps

Deployer Simple command-line tool that aims to facilitate the continous delivery of PHP apps, particularly Laravel apps. Imagine you want to update yo

Sep 8, 2021
🍃 In short, it's like Tailwind CSS, but for the PHP command-line applications.
🍃 In short, it's like Tailwind CSS, but for the PHP command-line applications.

Termwind Termwind allows you to build unique and beautiful PHP command-line applications, using the Tailwind CSS API. In short, it's like Tailwind CSS

May 27, 2022
A PHP Command Line tool that makes it easy to compile, concat, and minify front-end Javascript and CSS/SCSS dependencies.

Front End Compiler A PHP Command Line tool that makes it easy to compile, concat, and minify front-end Javascript and CSS/SCSS dependencies. The minif

Nov 12, 2021
php command line script to DCA crypto from Coinbase Pro

dca.php A simple php script designed to be run via the command line via a cron job. This will connect to coinbase pro and buy the crypto coins specifi

Oct 22, 2021