multi-docker-commander (mdc)

日本語版のREAMDEはこちら

A CLI tool for managing and running the start/stop of Docker environments across multiple repositories with a single command.

While docker-compose has the -d option for background execution, mdc can also daemonize foreground commands like npm run dev and provides the flexibility to manage processes (stop, restart, view logs).

Features

• Batch operation of Docker Compose across multiple repositories with mdc up / mdc down
• Selectable parallel / sequential execution modes between projects
• Background process management and status monitoring (mdc proc)
• Project name prefix in log output for better visibility
• Configuration file management (mdc init / mdc edit / mdc rm)
• Simple YAML-based configuration files

Installation

Homebrew

brew tap tominaga-h/tap
brew install tominaga-h/tap/mdc

Download from GitHub Releases

Pre-built binaries are available on the latest release page.

Supported platforms

OS	Architecture	Asset name
macOS (Apple Silicon)	arm64	mdc-<version>-darwin-arm64
macOS (Intel)	amd64	mdc-<version>-darwin-amd64
Linux	amd64	mdc-<version>-linux-amd64
Linux	arm64	mdc-<version>-linux-arm64
Windows	amd64	mdc-<version>-windows-amd64.exe

Each asset ships with a matching .sha256 file for checksum verification.

Install (macOS / Linux)

1. Download the binary matching your OS / architecture (e.g. mdc-v2.0.3-darwin-arm64) and the matching .sha256 file from the release page.

2. Verify the checksum:

   shasum -a 256 -c mdc-v2.0.3-darwin-arm64.sha256

3. Make it executable and move it onto your PATH:

   chmod +x mdc-v2.0.3-darwin-arm64
   sudo mv mdc-v2.0.3-darwin-arm64 /usr/local/bin/mdc

Install (Windows)

1. Download mdc-<version>-windows-amd64.exe and the matching .sha256 file from the release page.

2. Verify the checksum:

   Get-FileHash mdc-v2.0.3-windows-amd64.exe -Algorithm SHA256

3. Rename the file to mdc.exe and place it in a directory on your PATH.

Build from Source

git clone https://github.com/tominaga-h/multi-docker-commander.git
cd multi-docker-commander
make build

This generates the ./mdc binary. Copy it to a directory in your PATH.

Version-embedded Build

To embed version information from Git tags:

make build-v

Quick Start

1. Create a Configuration File

mdc init myproject

This creates a template at configulation directory. To open it in your editor immediately:

mdc init myproject --edit

2. Edit the Configuration File

Edit the generated template to match your project setup:

execution_mode: "parallel"
projects:
  - name: "Frontend"
    path: "/path/to/frontend-repo"
    commands:
      up:
        - command: "docker compose up -d"
        - command: "npm run dev"
          background: true
      down:
        - command: "docker compose down"

  - name: "Backend-API"
    path: "/path/to/backend-api-repo"
    commands:
      up:
        - command: "docker compose up -d"
      down:
        - command: "docker compose down"

You can also open the file later with mdc edit myproject.

3. Start and Stop

mdc up myproject      # Start all projects
mdc down myproject    # Stop all projects

The .yml extension can be omitted.

4. Check Background Processes

mdc proc list
mdc procs

Displays a table of background processes:

+--------------+------------+-------------+------------------------+-------+---------+
| CONFIG       | PROJECT    | COMMAND     | DIR                    |   PID | STATUS  |
+--------------+------------+-------------+------------------------+-------+---------+
| myproject    | Frontend   | npm run dev | /path/to/frontend-repo | 88888 | Running |
+--------------+------------+-------------+------------------------+-------+---------+

5. Stop / Restart Background Processes

mdc proc stop <PID>
mdc proc restart <PID>

6. View Background Process Logs

mdc proc attach <PID>

Configuration

Configuration files are placed in ~/.config/mdc/ in YAML format.

The ~ portion is your OS user home directory, so the actual path differs per environment:

OS	Path
macOS	/Users/<username>/.config/mdc/<name>.yml
Linux	/home/<username>/.config/mdc/<name>.yml
Windows	C:\Users\<username>\.config\mdc\<name>.yml

(The directory layout is the same everywhere — only the user home prefix changes.)

Field Reference

Field	Required	Description
execution_mode	Yes	"parallel" or "sequential"
projects	Yes	List of project definitions (one or more)
projects[].name	Yes	Project name (used as log output prefix)
projects[].path	Yes	Project directory path (~ expansion supported)
projects[].commands.up	No	List of command objects to run on start
projects[].commands.down	No	List of command objects to run on stop
commands[][].command	Yes	Command string to execute
commands[][].background	No	Set to true for background execution (default: false)

Command Format

Commands are written as objects with command and background fields:

commands:
  up:
    - command: "docker compose up -d"
      background: true
    - command: "echo done"

Omitting background defaults to foreground execution:

commands:
  down:
    - command: "docker compose down"

For backward compatibility, plain string format is also supported:

commands:
  down:
    - "docker compose down"

You can use mdc proc kill in commands.down to stop all background processes managed by mdc. The runner automatically appends -c <config-name>, so you only need to write mdc proc kill:

commands:
  down:
    - command: "docker compose down"
    - command: "mdc proc kill"

Execution Modes

• parallel: All projects run concurrently using Goroutines. Commands within each project are still executed sequentially.
• sequential: Projects are processed one at a time in definition order.

Command Reference

mdc up [config-name]

Loads the specified configuration file and executes each project's commands.up.

mdc up myproject

mdc down [config-name]

Loads the specified configuration file and executes each project's commands.down. Background processes started by mdc up are also automatically stopped.

mdc down myproject

mdc list

Lists configuration files in ~/.config/mdc/. Also available as mdc ls.

mdc list
mdc ls

mdc init <config-name>

Creates a new YAML configuration template in ~/.config/mdc/. The .yml extension can be omitted.

mdc init myproject           # Creates ~/.config/mdc/myproject.yml
mdc init myproject --edit    # Create and open in $EDITOR
mdc init myproject -e        # Short form

Option	Description
--edit, -e	Open the created file in $EDITOR after creation

mdc edit <config-name>

Opens the specified configuration file in your editor. Uses the $EDITOR environment variable, or falls back to vim if not set.

mdc edit myproject

mdc rm <config-name>

Removes the specified configuration file from ~/.config/mdc/. Prompts for confirmation before deletion.

mdc rm myproject             # Prompts "Are you sure? [y/n]"
mdc rm myproject --force     # Skip confirmation
mdc rm myproject -f          # Short form

Option	Description
--force, -f	Skip the confirmation prompt

mdc proc (alias: mdc procs)

Manages background processes. When called without a subcommand, it behaves as proc list.

mdc proc list [config-name]

Lists background processes managed by mdc. When config name is omitted, shows processes for all configurations.

mdc proc list              # Show all processes
mdc proc list myproject    # Show processes for a specific config
mdc procs                  # Alias (equivalent to proc list)

mdc proc attach <PID>

Streams log output from a background process. Press Ctrl-C to detach (the process continues running).

mdc proc attach 12345
mdc proc attach 12345 --tail 50       # Start from the last 50 lines
mdc proc attach 12345 --no-follow     # Print existing logs and exit

mdc proc stop <PID>

Stops the background process with the specified PID.

mdc proc stop 12345

mdc proc restart <PID>

Restarts the background process with the specified PID.

mdc proc restart 12345

mdc proc kill

Kills background processes by config name, PID, or all configs. Use -c to kill all processes belonging to a config, -p to kill a single process by PID, or --all to kill all tracked processes.

Use --dead to remove tracked entries whose process is no longer running (Status: Dead) without killing any live process. It can be combined with -c to clean a single config, or used alone / with --all to clean every config. --dead cannot be combined with -p.

When mdc proc kill is used in YAML commands.down, the runner automatically appends -c <config-name>.

mdc proc kill -c myproject    # Kill all processes for a config
mdc proc kill -p 12345        # Kill a single process by PID
mdc proc kill --all           # Kill all tracked processes across all configs
mdc proc kill --dead          # Remove dead entries across all configs
mdc proc kill --dead -c myproject  # Remove dead entries for one config

Option	Description
-c, --config	Config name to kill all processes for
-p, --pid	PID of the process to kill
--all	Kill all tracked processes across all configs
--dead	Remove tracked entries whose process is no longer running (does not kill live processes; combinable with -c)

mdc --version

Displays version information.

mdc --version
mdc -v

Development

Requirements

• Go 1.25+

Build

make build

Test

make test             # Internal package tests
make test-integration # Integration tests
make test-all         # All tests
make test-cover       # Tests with coverage
make lint             # go vet + golangci-lint
make check            # lint + test-all

License

TBD