multiplex-sh 1.0.0

A command-line multiplexer for running multiple processes in parallel with coordination

              .__   __  .__       .__
  _____  __ __|  |_/  |_|__|_____ |  |   ____ ___  ___
 /     \|  |  \  |\   __\  \____ \|  | _/ __ \\  \/  /
|  Y Y  \  |  /  |_|  | |  |  |_> >  |_\  ___/ >    <
|__|_|  /____/|____/__| |__|   __/|____/\___  >__/\_ \
      \/                   |__|             \/      \/

Multiplex is a command-line multiplexer along with a simple Python API to run multiple processes in parallel and stop them all at once, or based on some condition.

Multiplex will gracefully shutdown child processes, and multiplex their output and error streams to stdout and stderr in a way that is easily parsable with regular command line tools.

Multiplex is useful when you need to run multiple programs all at once and combine their output. For instance, you need a webserver, a workqueue and a database to run standalone all together. You could write a shell script, or you could write a one liner using multiplex.

Here's how you'd benchmark Python's embedded HTTP server with a one-liner:

multiplex "|silent=python -m http.server" "+1|end=ab -n1000 http://localhost:8000/"

Installing

Multiplex is available on PyPI at https://pypi.org/project/multiplex-sh

Using uv (recommended)

$ uv tool install multiplex-sh
$ multiplex --help

Using pip

$ pip install multiplex-sh
$ multiplex --help

Direct download

Quick, from the shell:

$ curl -o multiplex https://raw.githubusercontent.com/sebastien/multiplex/main/src/py/multiplex.py; chmod +x multiplex
$ ./multiplex --help

Usage

Commands

Here are some example commands that will help understand the syntax:

Running a simple command:

multiplex "python -m http.server"

Running a command after 5s delay:

multiplex "+5=python -m http.server"

Running a command after another completes:

multiplex "A=python -m http.server" "+A=ab -n1000 http://localhost:8000/"

Running multiple commands with complex coordination:

multiplex "DB=mongod" "API+2=node server.js" "+API|end=npm test"

Command Syntax

Commands follow a structured format: [KEY][+DELAY][|ACTIONS]=COMMAND

Naming (KEY=)

• Purpose: Assign a name to a process for reference by other commands
• Format: KEY=command where KEY is alphanumeric (A-Z, a-z, 0-9, _)
• Examples:
  • A=python -m http.server
  • DB=mongod --port 27017
  • API_SERVER=node app.js

Delays (+DELAY)

Commands can be delayed in two ways:

Time-based delays

• Format: +SECONDS where SECONDS can be integer or decimal
• Examples:
  • +5=python script.py (wait 5 seconds)
  • +1.5=echo "delayed" (wait 1.5 seconds)
  • SERVER+10=curl localhost:8000 (named SERVER, wait 10s)

Process-based delays

• Format: +PROCESS_NAME wait for named process to complete
• Examples:
  • +A=ab -n1000 http://localhost:8000/ (wait for process A)
  • +DB=node migrate.js (wait for DB process to complete)
  • +SERVER=echo "server is done" (wait for SERVER process)

Actions (|ACTION)

Actions modify process behavior:

• |end: When this process ends, terminate all other processes
• |silent: Suppress all output (stdout and stderr)
• |noout: Suppress stdout only
• |noerr: Suppress stderr only

Actions can be combined: |silent|end=command

Examples by Pattern

Sequential execution:

multiplex "BUILD=npm run build" "+BUILD=npm start"

Parallel with coordination:

multiplex "DB=mongod" "API+2=node server.js" "+API=npm test"

Benchmark pattern:

multiplex "SERVER|silent=python -m http.server" "+1|end=ab -n1000 http://localhost:8000/"

Development environment:

multiplex "DB=mongod" "API+2=npm run dev" "UI+2=npm run ui" "+5=open http://localhost:3000"

Special Cases

If your command contains an equals sign, use an empty prefix:

multiplex "=echo a=b"

Global Options

Timeout:

• Format: -t|--timeout SECONDS
• Purpose: Terminate all processes after specified time
• Example: multiplex -t 30 "server=python -m http.server" "test=curl localhost:8000"

Examples

The examples/ directory contains practical demonstrations of multiplex features:

Basic Patterns

Sequential Build (examples/sequential-build.sh)

multiplex "BUILD=echo 'Building...'" "+BUILD=echo 'Starting...'"

Demonstrates process-based delays where one command waits for another to complete.

Time-based Delays (examples/time-delays.sh)

multiplex "echo 'immediate'" "+1=echo 'after 1s'" "+2.5=echo 'after 2.5s'"

Shows different timing patterns with integer and decimal delays.

Process Dependencies (examples/process-delays.sh)

multiplex "STEP1=echo 'init'" "STEP2+STEP1=echo 'process'" "+STEP2=echo 'done'"

Demonstrates chaining processes where each waits for the previous to complete.

Real-world Scenarios

Development Environment (examples/dev-environment.sh)

multiplex "DB=mongod" "API+2=node server.js" "UI+2=npm run ui" "+5=open browser"

Simulates starting a full development stack with proper coordination.

Parallel Coordination (examples/parallel-coordination.sh)

multiplex "DB=database" "API+2=api-server" "UI+2=ui-server" "+5=open-browser"

Shows how to coordinate multiple services starting in parallel with delays.

CI/CD Pipeline (examples/cicd-pipeline.sh)

multiplex "BUILD=build" "+BUILD=test" "+TESTS=deploy|end"

Demonstrates a realistic deployment pipeline with sequential steps.

Advanced Features

Actions Demo (examples/actions-demo.sh)

multiplex "SERVER|silent=long-running" "+2|end=test-and-exit"

Shows silent processes and automatic termination with |end action.

HTTP Benchmark (examples/http-benchmark.sh)

multiplex "A=python -m http.server" "+A=ab -n1000 http://localhost:8000/"

Real HTTP server benchmarking where the test waits for server startup.

Special Cases (examples/special-cases.sh)

multiplex "=echo 'VAR=value'" "SETUP|silent=setup" "+SETUP=continue"

Handles commands with equals signs and complex action combinations.

Complete Demo (examples/complete-demo.sh)

multiplex "SETUP|silent=setup" "DB+1=database" "API+DB=api" "UI+API=ui" "+UI|end=done"

Comprehensive example showcasing all features: naming, time/process delays, actions, and coordination.

Running Examples

All examples are executable scripts:

cd multiplex
bash examples/sequential-build.sh
bash examples/dev-environment.sh
bash examples/http-benchmark.sh

Each example includes descriptive output explaining what's happening during execution.