Home

Awesome

mprocs

mprocs runs multiple commands in parallel and shows output of each command separately.

When you work on a project you very often need the same list of commands to be running. For example: webpack serve, jest --watch, node src/server.js. With mprocs you can list these command in mprocs.yaml and run all of them by running mprocs. Then you can switch between outputs of running commands and interact with them.

It is similar to concurrently but mprocs shows output of each command separately and allows to interact with processes (you can even work in vim inside mprocs).

<!--ts--> <!-- Created by https://github.com/ekalinin/github-markdown-toc --> <!-- Added by: pvolok, at: Sun Jul 3 22:53:57 +07 2022 --> <!--te-->

Screenshots

<img src="img/screenshot1.png" width="900" height="645" /> <img src="img/screenshot2.png" width="900" height="645" />

Installation

Packaging status

Download binary (Linux, Macos, Windows)

Download executable for your platform and put it into a directory included in PATH.

npm (Linux, Macos, Windows)

npm install -g mprocs
yarn global add mprocs

homebrew (Macos, Linux)

brew install mprocs

cargo (All platforms)

cargo install mprocs

scoop (Windows)

scoop install mprocs

AUR (Arch Linux)

yay mprocs
yay mprocs-bin

MPR (Debian/Ubuntu)

git clone 'https://mpr.makedeb.org/mprocs'
cd mprocs/
makedeb -si

Usage

  1. Run mprocs cmd1 cmd2 … (example: mprocs "yarn test -w" "webpack serve")

OR

  1. Create mprocs.yaml file
  2. Run mprocs command

Example mprocs.yaml:

procs:
  nvim:
    cmd: ["nvim"]
  server:
    shell: "nodemon server.js"
  webpack: "webpack serve"
  tests:
    shell: "jest -w"
    env:
      NODE_ENV: test

Config

JSON/YAML Configuration Schema

There are two kinds of configs: global and local. Global config is loaded from ~/.config/mprocs/mprocs.yaml (or ~\AppData\Roaming\mprocs\mprocs.yaml on Windows). Local config is loaded from mprocs.yaml from current directory (or set via cli argument: mprocs --config ./cfg/mprocs.yaml). Settings in the local config override settings the global.

Keymap

Default key bindings can be overridden in config using keymap_procs, keymap_term, or keymap_copy fields. Available commands are documented in the Remote control section.

There are three keymap levels:

Lower levers override bindings from previous levels. Key bindings from previous levels can be cleared by specifying reset: true field at the same level as keys.

Key bindings are defined between < and >, e.g., <Enter> (enter key), <Down> (down arrow), <Up> (up arrow), <C-q> (CTRL + q).

keymap_procs: # keymap when process list is focused
  <C-q>: { c: toggle-focus }
  <C-a>: null # unbind key
keymap_term: # keymap when terminal is focused
  reset: true
  <C-q>: { c: toggle-focus }
  <C-j>:
    c: batch
    cmds:
      - { c: focus-procs }
      - { c: next-proc }

$select operator

You can define different values depending on the current operating system. Any value in config can be wrapped with a $select operator. To provide different values based on current OS define an object with:

Example mprocs.yaml:

procs:
  my process:
    shell:
      $select: os
      windows: "echo %TEXT%"
      $else: "echo $TEXT"
    env:
      TEXT:
        $select: os
        windows: Windows
        linux: Linux
        macos: Macos
        freebsd: FreeBSD

Running scripts from package.json

If you run mprocs with an --npm argument, it will load scripts from package.json. But the scripts are not run by default, and you can launch desired scripts manually.

# Run mprocs with scripts from package.json
mprocs --npm

Default keymap

Process list focused:

Process output focused:

Copy mode:

Remote control

Optionally, mprocs can listen on TCP port for remote commands. You have to define remote control server address in mprocs.yaml (server: 127.0.0.1:4050) or via cli argument (mprocs --server 127.0.0.1:4050). To send a command to running mprocs instance use the ctl argument: mprocs --ctl '{c: quit}' or mprocs --ctl '{c: send-key, key: <C-c>}'.

Commands are encoded as yaml. Available commands:

FAQ

mprocs vs tmux/screen

mprocs is meant to make it easier to run specific commands that you end up running repeatedly, such as compilers and test runners. This is in contrast with tmux, which is usually used to run much more long-lived processes - usually a shell - in each window/pane. Another difference is that tmux runs a server and a client, which allows the client to detach and reattach later, keeping the processes running. mprocs is meant more for finite lifetime processes that you keep re-running, but when mprocs ends, so do the processes it is running within its windows.

Copying doesn't work in tmux

Tmux doesn't have escape sequences for copying enabled by default. To enable it add the following to ~/.tmux.conf:

set -g set-clipboard on