How do you pass an argument to a composer script from the command line?

You may add the double dashes -- to the end of your script entry(s).

This way you can pass additional arguments/options to the underlying script.

{
    "scripts": {
        "test": "phpunit",
        "test-single": "phpunit --"
    }
}

To run the test-single script with a custom phpunit filter:

composer test-single --filter test_function

Any kind of arguments may be passed to custom-composer-scripts simply by appending them on the command-line as usual but after a -- (i.e. the special argument separation operator, which is not passed to the scripts itself).

However, you do not need to use the -- argument separation operator when NONE of the arguments begin with any hyphens (i.e. what are generally called command-line options, like -o or --option) else composer would treat them as an option to composer itself, and not to the script.

If the custom script definition runs multiple commands then the arguments passed will appended to every command. Also you can't use shell programming conventions like $2 to refer to individual arguments.

If the custom script is handled by a callback, it is the script's responsibility to parse options from arguments. From the callback's perspective things like -c and --option=B are arguments.

Example

Given a composer.json with the following contents:

{
    "autoload": { "psr-4": { "MyVendor\\": "./" } },
    "scripts": {
        "pass-args-to-callback": [
            "MyVendor\\MyClass::myCallback"
        ],
        "pass-args-to-commands": [
            "echo one",
            "echo two",
            "@other-command"
        ],
        "other-command": [
            "echo three"
        ]
    }
}

And given a file MyClass.php with the following contents:

<?php
namespace MyVendor;

use Composer\Script\Event;
use Composer\Installer\PackageEvent;

class MyClass {
    public static function myCallback(Event $event) {
        var_dump($event->getArguments());
    }
}

Step 0: Dump Autoloader to recognize MyClass

$ composer dump-autoload
Generating autoload files

Test 1: Show what happens without the argument separation operator

$ composer pass-args-to-callback A --option=B -C


  [Symfony\Component\Console\Exception\RuntimeException]
  The "--option" option does not exist.


pass-args-to-callback [--dev] [--no-dev] [--] [<args>]...

Test 2: Show how arguments and options appear in the callback

$ composer pass-args-to-callback -- A --option=B -C
> MyVendor\MyClass::myCallback
array(3) {
  [0]=>
  string(1) "A"
  [1]=>
  string(10) "--option=B"
  [2]=>
  string(2) "-C"
}

Test 3: Show how arguments and options are appended to commands

$ composer pass-args-to-commands -- A --option=B -C
> echo one 'A' '--option=B' '-C'
one A --option=B -C
> echo two 'A' '--option=B' '-C'
two A --option=B -C
> echo three 'A' '--option=B' '-C'
three A --option=B -C

Reference: https://getcomposer.org/doc/articles/scripts.md