```
.__ __ .__ .__
_____ __ __| |_/ |_|__|_____ | | ____ ___ ___
/ \| | \ |\ __\ \____ \| | _/ __ \\ \/ /
| 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:**
```bash
multiplex "BUILD=npm run build" "+BUILD=npm start"
```
**Parallel with coordination:**
```bash
multiplex "DB=mongod" "API+2=node server.js" "+API=npm test"
```
**Benchmark pattern:**
```bash
multiplex "SERVER|silent=python -m http.server" "+1|end=ab -n1000 http://localhost:8000/"
```
**Development environment:**
```bash
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:
```bash
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`)**
```bash
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`)**
```bash
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`)**
```bash
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`)**
```bash
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`)**
```bash
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`)**
```bash
multiplex "BUILD=build" "+BUILD=test" "+TESTS=deploy|end"
```
Demonstrates a realistic deployment pipeline with sequential steps.
## Advanced Features
**Actions Demo (`examples/actions-demo.sh`)**
```bash
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`)**
```bash
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`)**
```bash
multiplex "=echo 'VAR=value'" "SETUP|silent=setup" "+SETUP=continue"
```
Handles commands with equals signs and complex action combinations.
**Complete Demo (`examples/complete-demo.sh`)**
```bash
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:
```bash
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/sebastien/multiplex",
"name": "multiplex-sh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "multiplex process command parallel concurrent shell cli automation build coordination orchestration",
"author": "S\u00e9bastien Pierre",
"author_email": "sebastien@ffctn.com",
"download_url": "https://files.pythonhosted.org/packages/86/85/24469f729928605986579797e24e464c9f03d79c716ad2fc83adfe672424/multiplex_sh-1.0.0.tar.gz",
"platform": "unix",
"description": "``` \n .__ __ .__ .__\n _____ __ __| |_/ |_|__|_____ | | ____ ___ ___\n / \\| | \\ |\\ __\\ \\____ \\| | _/ __ \\\\ \\/ /\n| Y Y \\ | / |_| | | | |_> > |_\\ ___/ > <\n|__|_| /____/|____/__| |__| __/|____/\\___ >__/\\_ \\\n \\/ |__| \\/ \\/\n```\n\n**Multiplex** is a command-line multiplexer along with a simple Python\nAPI to run multiple processes in parallel and stop them all at once, or\nbased on some condition.\n\nMultiplex will gracefully shutdown child processes, and multiplex their\noutput and error streams to stdout and stderr in a way that is easily\nparsable with regular command line tools.\n\nMultiplex is useful when you need to run multiple programs all at once\nand combine their output. For instance, you need a webserver, a\nworkqueue and a database to run standalone all together. You could write\na shell script, or you could write a one liner using `multiplex`.\n\nHere's how you'd benchmark Python's embedded HTTP server with a\none-liner:\n\n multiplex \"|silent=python -m http.server\" \"+1|end=ab -n1000 http://localhost:8000/\"\n\n# Installing\n\nMultiplex is available on PyPI at https://pypi.org/project/multiplex-sh\n\n## Using uv (recommended)\n\n $ uv tool install multiplex-sh\n $ multiplex --help\n\n## Using pip\n\n $ pip install multiplex-sh\n $ multiplex --help\n\n## Direct download\n\nQuick, from the shell:\n\n $ curl -o multiplex https://raw.githubusercontent.com/sebastien/multiplex/main/src/py/multiplex.py; chmod +x multiplex\n $ ./multiplex --help\n\n# Usage\n\n## Commands\n\nHere are some example commands that will help understand the syntax:\n\nRunning a simple command:\n\n multiplex \"python -m http.server\"\n\nRunning a command after 5s delay:\n\n multiplex \"+5=python -m http.server\"\n\nRunning a command after another completes:\n\n multiplex \"A=python -m http.server\" \"+A=ab -n1000 http://localhost:8000/\"\n\nRunning multiple commands with complex coordination:\n\n multiplex \"DB=mongod\" \"API+2=node server.js\" \"+API|end=npm test\"\n\n## Command Syntax\n\nCommands follow a structured format: `[KEY][+DELAY][|ACTIONS]=COMMAND`\n\n### Naming (`KEY=`)\n- **Purpose**: Assign a name to a process for reference by other commands\n- **Format**: `KEY=command` where KEY is alphanumeric (A-Z, a-z, 0-9, _)\n- **Examples**: \n - `A=python -m http.server`\n - `DB=mongod --port 27017`\n - `API_SERVER=node app.js`\n\n### Delays (`+DELAY`)\nCommands can be delayed in two ways:\n\n#### Time-based delays\n- **Format**: `+SECONDS` where SECONDS can be integer or decimal\n- **Examples**:\n - `+5=python script.py` (wait 5 seconds)\n - `+1.5=echo \"delayed\"` (wait 1.5 seconds)\n - `SERVER+10=curl localhost:8000` (named SERVER, wait 10s)\n\n#### Process-based delays \n- **Format**: `+PROCESS_NAME` wait for named process to complete\n- **Examples**:\n - `+A=ab -n1000 http://localhost:8000/` (wait for process A)\n - `+DB=node migrate.js` (wait for DB process to complete)\n - `+SERVER=echo \"server is done\"` (wait for SERVER process)\n\n### Actions (`|ACTION`)\nActions modify process behavior:\n\n- **`|end`**: When this process ends, terminate all other processes\n- **`|silent`**: Suppress all output (stdout and stderr)\n- **`|noout`**: Suppress stdout only\n- **`|noerr`**: Suppress stderr only\n\nActions can be combined: `|silent|end=command`\n\n### Examples by Pattern\n\n**Sequential execution:**\n```bash\nmultiplex \"BUILD=npm run build\" \"+BUILD=npm start\"\n```\n\n**Parallel with coordination:**\n```bash\nmultiplex \"DB=mongod\" \"API+2=node server.js\" \"+API=npm test\"\n```\n\n**Benchmark pattern:**\n```bash\nmultiplex \"SERVER|silent=python -m http.server\" \"+1|end=ab -n1000 http://localhost:8000/\"\n```\n\n**Development environment:**\n```bash\nmultiplex \"DB=mongod\" \"API+2=npm run dev\" \"UI+2=npm run ui\" \"+5=open http://localhost:3000\"\n```\n\n### Special Cases\n\nIf your command contains an equals sign, use an empty prefix:\n```bash\nmultiplex \"=echo a=b\"\n```\n\n### Global Options\n\n**Timeout:**\n- **Format**: `-t|--timeout SECONDS`\n- **Purpose**: Terminate all processes after specified time\n- **Example**: `multiplex -t 30 \"server=python -m http.server\" \"test=curl localhost:8000\"`\n\n# Examples\n\nThe `examples/` directory contains practical demonstrations of multiplex features:\n\n## Basic Patterns\n\n**Sequential Build (`examples/sequential-build.sh`)**\n```bash\nmultiplex \"BUILD=echo 'Building...'\" \"+BUILD=echo 'Starting...'\"\n```\nDemonstrates process-based delays where one command waits for another to complete.\n\n**Time-based Delays (`examples/time-delays.sh`)**\n```bash\nmultiplex \"echo 'immediate'\" \"+1=echo 'after 1s'\" \"+2.5=echo 'after 2.5s'\"\n```\nShows different timing patterns with integer and decimal delays.\n\n**Process Dependencies (`examples/process-delays.sh`)**\n```bash\nmultiplex \"STEP1=echo 'init'\" \"STEP2+STEP1=echo 'process'\" \"+STEP2=echo 'done'\"\n```\nDemonstrates chaining processes where each waits for the previous to complete.\n\n## Real-world Scenarios\n\n**Development Environment (`examples/dev-environment.sh`)**\n```bash\nmultiplex \"DB=mongod\" \"API+2=node server.js\" \"UI+2=npm run ui\" \"+5=open browser\"\n```\nSimulates starting a full development stack with proper coordination.\n\n**Parallel Coordination (`examples/parallel-coordination.sh`)**\n```bash\nmultiplex \"DB=database\" \"API+2=api-server\" \"UI+2=ui-server\" \"+5=open-browser\"\n```\nShows how to coordinate multiple services starting in parallel with delays.\n\n**CI/CD Pipeline (`examples/cicd-pipeline.sh`)**\n```bash\nmultiplex \"BUILD=build\" \"+BUILD=test\" \"+TESTS=deploy|end\"\n```\nDemonstrates a realistic deployment pipeline with sequential steps.\n\n## Advanced Features\n\n**Actions Demo (`examples/actions-demo.sh`)**\n```bash\nmultiplex \"SERVER|silent=long-running\" \"+2|end=test-and-exit\"\n```\nShows silent processes and automatic termination with `|end` action.\n\n**HTTP Benchmark (`examples/http-benchmark.sh`)**\n```bash\nmultiplex \"A=python -m http.server\" \"+A=ab -n1000 http://localhost:8000/\"\n```\nReal HTTP server benchmarking where the test waits for server startup.\n\n**Special Cases (`examples/special-cases.sh`)**\n```bash\nmultiplex \"=echo 'VAR=value'\" \"SETUP|silent=setup\" \"+SETUP=continue\"\n```\nHandles commands with equals signs and complex action combinations.\n\n**Complete Demo (`examples/complete-demo.sh`)**\n```bash\nmultiplex \"SETUP|silent=setup\" \"DB+1=database\" \"API+DB=api\" \"UI+API=ui\" \"+UI|end=done\"\n```\nComprehensive example showcasing all features: naming, time/process delays, actions, and coordination.\n\n## Running Examples\n\nAll examples are executable scripts:\n```bash\ncd multiplex\nbash examples/sequential-build.sh\nbash examples/dev-environment.sh\nbash examples/http-benchmark.sh\n```\n\nEach example includes descriptive output explaining what's happening during execution.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A command-line multiplexer for running multiple processes in parallel with coordination",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/sebastien/multiplex/issues",
"Documentation": "https://github.com/sebastien/multiplex#readme",
"Homepage": "https://github.com/sebastien/multiplex",
"Source": "https://github.com/sebastien/multiplex"
},
"split_keywords": [
"multiplex",
"process",
"command",
"parallel",
"concurrent",
"shell",
"cli",
"automation",
"build",
"coordination",
"orchestration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "31d686f2b8d78d64c82dbbfad0d17717179d7e15e23f1875521fd1c956664729",
"md5": "8b5f1f6a893a29bebb63c3cccac9c7ea",
"sha256": "73293c7d586c6755c6fea4abd5649061dd5291d2de035177c9dec7a8665d64d8"
},
"downloads": -1,
"filename": "multiplex_sh-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b5f1f6a893a29bebb63c3cccac9c7ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 22764,
"upload_time": "2025-07-28T04:26:15",
"upload_time_iso_8601": "2025-07-28T04:26:15.160407Z",
"url": "https://files.pythonhosted.org/packages/31/d6/86f2b8d78d64c82dbbfad0d17717179d7e15e23f1875521fd1c956664729/multiplex_sh-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "868524469f729928605986579797e24e464c9f03d79c716ad2fc83adfe672424",
"md5": "6dfbca515fa16f6999e5063e6128c182",
"sha256": "e5d67fefd108f424bec3090932d1327406af70151a25b8c093b8c836896b6e41"
},
"downloads": -1,
"filename": "multiplex_sh-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "6dfbca515fa16f6999e5063e6128c182",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 24737,
"upload_time": "2025-07-28T04:26:16",
"upload_time_iso_8601": "2025-07-28T04:26:16.837356Z",
"url": "https://files.pythonhosted.org/packages/86/85/24469f729928605986579797e24e464c9f03d79c716ad2fc83adfe672424/multiplex_sh-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 04:26:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sebastien",
"github_project": "multiplex",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "multiplex-sh"
}
JSON
