concurrently

Run commands concurrently. Like `npm run watch-js & npm run watch-less` but...

CLINPM scripts
open-cli-tools/concurrentlyconcurrently

README

concurrently


Latest Release License Weekly Downloads on NPM CI Status Coverage Status

Run multiple commands concurrently.
Like npm run watch-js & npm run watch-less but better.

Demo

Table of Contents

- concurrently
  - Why
  - Installation
  - Usage
  - API
    - [concurrently(commands[, options])](#concurrentlycommands-options)
    - [Command](#command)
    - [CloseEvent](#closeevent)
  - FAQ

Why


I like task automation with npm
but the usual way to run multiple commands concurrently is
npm run watch-js & npm run watch-css. That's fine but it's hard to keep
on track of different outputs. Also if one process fails, others still keep running
and you won't even notice the difference.

Another option would be to just run all commands in separate terminals. I got
tired of opening terminals and made concurrently.

Features:

- Cross platform (including Windows)
- Output is easy to follow with prefixes
- With --kill-others switch, all commands are killed if one dies
- Spawns commands with spawn-command

Installation


concurrently can be installed in the global scope (if you'd like to have it available and use it on the whole system) or locally for a specific package (for example if you'd like to use it in the scripts section of your package):

|Yarnpnpm
---------
**Global**`npm`yarn
**Local**\*`npm`yarn

\* It's recommended to add **concurrently** as `devDependencies` as it's usually used for developing purposes. Please change this flag if this doesn't apply in your case.

Usage


Note

The concurrently command is now also available under the shorthand alias conc.


The tool is written in Node.js, but you can use it to run any commands.

Remember to surround separate commands with quotes:

  1. ```bash
  2. concurrently "command1 arg" "command2 arg"
  3. ```

Otherwise concurrently would try to run 4 separate commands:
command1, arg, command2, arg.

In package.json, escape quotes:

  1. ```bash
  2. "start": "concurrently \"command1 arg\" \"command2 arg\""
  3. ```

NPM run commands can be shortened:

  1. ```bash
  2. concurrently "npm:watch-js" "npm:watch-css" "npm:watch-node"

  4. # Equivalent to:
  5. concurrently -n watch-js,watch-css,watch-node "npm run watch-js" "npm run watch-css" "npm run watch-node"
  6. ```

NPM shortened commands also support wildcards. Given the following scripts in
package.json:

  1. ```jsonc
  2. {
  3.   //...
  4.   "scripts": {
  5.     // ...
  6.     "watch-js": "...",
  7.     "watch-css": "...",
  8.     "watch-node": "..."
  9.     // ...
  10.   }
  11.   // ...
  12. }
  13. ```

  1. ```bash
  2. concurrently "npm:watch-*"

  4. # Equivalent to:
  5. concurrently -n js,css,node "npm run watch-js" "npm run watch-css" "npm run watch-node"

  7. # Any name provided for the wildcard command will be used as a prefix to the wildcard
  8. # part of the script name:
  9. concurrently -n w: npm:watch-*

  11. # Equivalent to:
  12. concurrently -n w:js,w:css,w:node "npm run watch-js" "npm run watch-css" "npm run watch-node"
  13. ```

Exclusion is also supported. Given the following scripts in package.json:

  1. ```jsonc
  2. {
  3.   // ...
  4.   "scripts": {
  5.     "lint:js": "...",
  6.     "lint:ts": "...",
  7.     "lint:fix:js": "...",
  8.     "lint:fix:ts": "..."
  9.     // ...
  10.   }
  11.   // ...
  12. }
  13. ```

  1. ```bash
  2. # Running only lint:js and lint:ts
  3. #   with lint:fix:js and lint:fix:ts excluded
  4. concurrently "npm:lint:*(!fix)"
  5. ```

Good frontend one-liner example here.

Help:

  1. ```
  2. concurrently [options] <command ...>

  4. General
  5.   -m, --max-processes   How many processes should run at once.
  6.                         Exact number or a percent of CPUs available (for example "50%").
  7.                         New processes only spawn after all restart tries
  8.                         of a process.                            [string]
  9.   -n, --names                  List of custom names to be used in prefix
  10.                         template.
  11.                         Example names: "main,browser,server"     [string]
  12.       --name-separator         The character to split <names> on. Example usage:
  13.                         -n "styles|scripts|server" --name-separator "|"
  14.                         [default: ","]
  15.   -s, --success         Which command(s) must exit with code 0 in order
  16.                         for concurrently exit with code 0 too. Options
  17.                         are:
  18.                         - "first" for the first command to exit;
  19.                         - "last" for the last command to exit;
  20.                         - "all" for all commands;
  21.                         - "command-{name}"/"command-{index}" for the
  22.                         commands with that name or index;
  23.                         - "!command-{name}"/"!command-{index}" for all
  24.                         commands but the ones with that name or index.
  25.                         [default: "all"]
  26.   -r, --raw                    Output only raw output of processes, disables
  27.                         prettifying and concurrently coloring.  [boolean]
  28.       --no-color               Disables colors from logging            [boolean]
  29.       --hide                   Comma-separated list of processes to hide the
  30.                         output.
  31.                         The processes can be identified by their name or
  32.                         index.                     [string] [default: ""]
  33.   -g, --group                  Order the output as if the commands were run
  34.                         sequentially.                           [boolean]
  35.       --timings                Show timing information for all processes.
  36.                         [boolean] [default: false]
  37.   -P, --passthrough-arguments  Passthrough additional arguments to commands
  38.                         (accessible via placeholders) instead of treating
  39.                         them as commands.      [boolean] [default: false]

  41. Prefix styling
  42.   -p, --prefix            Prefix used in logging for each process.
  43.                           Possible values: index, pid, time, command, name,
  44.                           none, or a template. Example template: "{time}-{pid}"
  45.                          [string] [default: index or name (when --names is set)]
  46.   -c, --prefix-colors     Comma-separated list of chalk colors to use on
  47.                           prefixes. If there are more commands than colors, the
  48.                           last color will be repeated.
  49.                           - Available modifiers: reset, bold, dim, italic,
  50.                           underline, inverse, hidden, strikethrough
  51.                           - Available colors: black, red, green, yellow, blue,
  52.                           magenta, cyan, white, gray,
  53.                           any hex values for colors (e.g. #23de43) or auto for
  54.                           an automatically picked color
  55.                           - Available background colors: bgBlack, bgRed,
  56.                           bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite
  57.                           See https://www.npmjs.com/package/chalk for more
  58.                           information.               [string] [default: "reset"]
  59.   -l, --prefix-length     Limit how many characters of the command is displayed
  60.                           in prefix. The option can be used to shorten the
  61.                           prefix when it is set to "command"
  62.                                                    [number] [default: 10]
  63.   -t, --timestamp-format  Specify the timestamp in moment/date-fns format.
  64.                             [string] [default: "yyyy-MM-dd HH:mm:ss.SSS"]

  66. Input handling
  67.   -i, --handle-input          Whether input should be forwarded to the child
  68.                               processes. See examples for more information.
  69.                                                     [boolean]
  70.       --default-input-target  Identifier for child process to which input on
  71.                               stdin should be sent if not specified at start of
  72.                               input.
  73.                               Can be either the index or the name of the
  74.                               process.                              [default: 0]

  76. Killing other processes
  77.   -k, --kill-others          Kill other processes if one exits or dies.[boolean]
  78.       --kill-others-on-fail  Kill other processes if one exits with non zero
  79.                              status code.                              [boolean]

  81. Restarting
  82.       --restart-tries  How many times a process that died should restart.
  83.                        Negative numbers will make the process restart forever.
  84.                        [number] [default: 0]
  85.       --restart-after  Delay time to respawn the process, in milliseconds.
  86.                        [number] [default: 0]

  88. Options:
  89.   -h, --help         Show help                                  [boolean]
  90.   -v, -V, --version  Show version number                        [boolean]


  93. Examples:

  95. - Output nothing more than stdout+stderr of child processes

  97.      $ concurrently --raw "npm run watch-less" "npm run watch-js"

  99. - Normal output but without colors e.g. when logging to file

  101.      $ concurrently --no-color "grunt watch" "http-server" > log

  103. - Custom prefix

  105.      $ concurrently --prefix "{time}-{pid}" "npm run watch" "http-server"

  107. - Custom names and colored prefixes

  109.      $ concurrently --names "HTTP,WATCH" -c "bgBlue.bold,bgMagenta.bold"
  110.      "http-server" "npm run watch"

  112. - Auto varying colored prefixes

  114.      $ concurrently -c "auto" "npm run watch" "http-server"

  116. - Mixing auto and manual colored prefixes

  118.      $ concurrently -c "red,auto" "npm run watch" "http-server" "echo hello"

  120. - Configuring via environment variables with CONCURRENTLY_ prefix

  122.      $ CONCURRENTLY_RAW=true CONCURRENTLY_KILL_OTHERS=true concurrently "echo
  123.      hello" "echo world"

  125. - Send input to default

  127.      $ concurrently --handle-input "nodemon" "npm run watch-js"
  128.      rs  # Sends rs command to nodemon process

  130. - Send input to specific child identified by index

  132.      $ concurrently --handle-input "npm run watch-js" nodemon
  133.      1:rs

  135. - Send input to specific child identified by name

  137.      $ concurrently --handle-input -n js,srv "npm run watch-js" nodemon
  138.      srv:rs

  140. - Shortened NPM run commands

  142.      $ concurrently npm:watch-node npm:watch-js npm:watch-css

  144. - Shortened NPM run command with wildcard (make sure to wrap it in quotes!)

  146.      $ concurrently "npm:watch-*"

  148. - Exclude patterns so that between "lint:js" and "lint:fix:js", only "lint:js"
  149. is ran

  151.      $ concurrently "npm:*(!fix)"

  153. - Passthrough some additional arguments via '{<number>}' placeholder

  155.      $ concurrently -P "echo {1}" -- foo

  157. - Passthrough all additional arguments via '{@}' placeholder

  159.      $ concurrently -P "npm:dev-* -- {@}" -- --watch --noEmit

  161. - Passthrough all additional arguments combined via '{*}' placeholder

  163.      $ concurrently -P "npm:dev-* -- {*}" -- --watch --noEmit

  165. For more details, visit https://github.com/open-cli-tools/concurrently
  166. ```

API


concurrently can be used programmatically by using the API documented below:

concurrently(commands[, options])


- commands: an array of either strings (containing the commands to run) or objects
  with the shape { command, name, prefixColor, env, cwd }.

- options (optional): an object containing any of the below:
  - cwd: the working directory to be used by all commands. Can be overriden per command.
    Default: process.cwd().
  - defaultInputTarget: the default input target when reading from inputStream.
    Default: 0.
  - handleInput: when true, reads input from process.stdin.
  - inputStream: a [Readable stream](https://nodejs.org/dist/latest-v10.x/docs/api/stream.html#stream_readable_streams)
    to read the input from. Should only be used in the rare instance you would like to stream anything other than process.stdin. Overrides handleInput.
  - pauseInputStreamOnFinish: by default, pauses the input stream (process.stdin when handleInput is enabled, or inputStream if provided) when all of the processes have finished. If you need to read from the input stream after concurrently has finished, set this to false. (#252).
  - killOthers: an array of exitting conditions that will cause a process to kill others.
    Can contain any of success or failure.
  - maxProcesses: how many processes should run at once.
  - outputStream: a [Writable stream](https://nodejs.org/dist/latest-v10.x/docs/api/stream.html#stream_writable_streams)
    to write logs to. Default: process.stdout.
  - prefix: the prefix type to use when logging processes output.
    Possible values: index, pid, time, command, name, none, or a template (eg [{time} process: {pid}]).
    Default: the name of the process, or its index if no name is set.
  - prefixColors: a list of colors as supported by chalk orauto for an automatically picked color.
    If concurrently would run more commands than there are colors, the last color is repeated, unless if the last color value is auto which means following colors are automatically picked to vary.
    Prefix colors specified per-command take precedence over this list.
  - prefixLength: how many characters to show when prefixing with command. Default: 10
  - raw: whether raw mode should be used, meaning strictly process output will
    be logged, without any prefixes, coloring or extra stuff.
  - successCondition: the condition to consider the run was successful.
    If first, only the first process to exit will make up the success of the run; if last, the last process that exits will determine whether the run succeeds.
    Anything else means all processes should exit successfully.
  - restartTries: how many attempts to restart a process that dies will be made. Default: 0.
  - restartDelay: how many milliseconds to wait between process restarts. Default: 0.
  - timestampFormat: a date-fns format
    to use when prefixing with time. Default: yyyy-MM-dd HH:mm:ss.ZZZ
  - additionalArguments: list of additional arguments passed that will get replaced in each command. If not defined, no argument replacing will happen.

Returns: an object in the shape { result, commands }.

>

- result: a Promise that resolves if the run was successful (according to successCondition option),

or rejects, containing an array of [CloseEvent](#CloseEvent), in the order that the commands terminated.

- commands: an array of all spawned [Commands](#Command).


Example:

  1. ```js
  2. const concurrently = require('concurrently');
  3. const { result } = concurrently(
  4.   [
  5.     'npm:watch-*',
  6.     { command: 'nodemon', name: 'server' },
  7.     { command: 'deploy', name: 'deploy', env: { PUBLIC_KEY: '...' } },
  8.     {
  9.       command: 'watch',
  10.       name: 'watch',
  11.       cwd: path.resolve(__dirname, 'scripts/watchers'),
  12.     },
  13.   ],
  14.   {
  15.     prefix: 'name',
  16.     killOthers: ['failure', 'success'],
  17.     restartTries: 3,
  18.     cwd: path.resolve(__dirname, 'scripts'),
  19.   }
  20. );
  21. result.then(success, failure);
  22. ```

Command


An object that contains all information about a spawned command, and ways to interact with it.
It has the following properties:

- index: the index of the command among all commands spawned.
- command: the command line of the command.
- name: the name of the command; defaults to an empty string.
- cwd: the current working directory of the command.
- env: an object with all the environment variables that the command will be spawned with.
- killed: whether the command has been killed.
- exited: whether the command exited yet.
- pid: the command's process ID.
- stdin: a Writable stream to the command's stdin.
- stdout: an RxJS observable to the command's stdout.
- stderr: an RxJS observable to the command's stderr.
- error: an RxJS observable to the command's error events (e.g. when it fails to spawn).
- timer: an RxJS observable to the command's timing events (e.g. starting, stopping).
- close: an RxJS observable to the command's close events.
  See [CloseEvent](#CloseEvent) for more information.
- start(): starts the command, setting up all
- kill([signal]): kills the command, optionally specifying a signal (e.g. SIGTERM, SIGKILL, etc).

CloseEvent


An object with information about a command's closing event.
It contains the following properties:

- command: a stripped down version of [Command](#command), including only name, command, env and cwd properties.
- index: the index of the command among all commands spawned.
- killed: whether the command exited because it was killed.
- exitCode: the exit code of the command's process, or the signal which it was killed with.
- timings: an object in the shape { startDate, endDate, durationSeconds }.

FAQ


- Process exited with code _null_?

  From Node child_process documentation,exit event:

  > This event is emitted after the child process ends. If the process
  > terminated normally, code is the final exit code of the process,
  > otherwise null. If the process terminated due to receipt of a signal,
  > signal is the string name of the signal, otherwise null.

  So _null_ means the process didn't terminate normally. This will make concurrently
  to return non-zero exit code too.

- Does this work with the npm-replacements yarn or pnpm?

  Yes! In all examples above, you may replace "npm" with "yarn" or "pnpm".