PMT - Project Management Toolkit

Universal CLI for managing Docker dev environments across multiple projects.

  ██████╗ ███╗   ███╗████████╗
  ██╔══██╗████╗ ████║╚══██╔══╝
  ██████╔╝██╔████╔██║   ██║
  ██╔═══╝ ██║╚██╔╝██║   ██║
  ██║     ██║ ╚═╝ ██║   ██║
  ╚═╝     ╚═╝     ╚═╝   ╚═╝

One tool to start, stop, monitor and shell into any project — whether it's a single Docker Compose stack or a multi-repo platform with ordered startup dependencies.

Prerequisites

• Node.js v18+
• GitHub CLI (gh) — required for pmt clone

  brew install gh    # macOS
  gh auth login      # authenticate

Install

git clone https://github.com/your-org/pmt.git
cd pmt
npm install
npm link   # makes `pmt` available globally

Quick start

# Create your config
cp config/projects.example.yaml ~/.config/pmt/projects.yaml
pmt config edit

# Or if your team has a shared config repo:
pmt config link /path/to/your-pmt-config

Usage

pmt                            # interactive TUI dashboard
pmt list                       # all projects + container status
pmt up myproject               # start all services (ordered)
pmt up myproject api           # start a single service
pmt down myproject             # stop (reverse order)
pmt ps myproject               # container status table
pmt logs myproject api         # stream logs
pmt shell myproject api        # open shell in container
pmt clone myproject            # clone repo from GitHub
pmt clone                      # clone all missing projects
pmt clone myproject --init     # clone and initialize
pmt init myproject             # run project setup
pmt init myproject --fresh     # fresh setup (drop + recreate)
pmt run myproject migrate      # run custom command
pmt run myproject              # list available custom commands

Flags

Flag	Description
-e, --env <env>	Environment variant (local, dev, stage, prod)
--build	Rebuild containers before starting
--fresh	Fresh initialization (drop & recreate)
-v, --verbose	Verbose output

Interactive dashboard

Run pmt with no arguments to launch a full TUI:

• Navigate projects with j/k or arrow keys
• Quick actions: u up, d down, r restart, i init
• ? for help, q to quit
• Live container status updates every 5s

Configuration

PMT looks for config in this order:

1. $PMT_CONFIG environment variable
2. .pmt/projects.yaml (walking up from CWD)
3. ~/.config/pmt/projects.yaml

Paths in config support ~ for home directory and {env} for environment substitution in commands.

Team setup

Keep your config in a separate private repo and symlink it:

pmt config link /path/to/team-pmt-config   # creates symlink at ~/.config/pmt/projects.yaml
pmt config path                             # show active config location
pmt config edit                             # open in $EDITOR

Adding a new project

Single-service project (most common)

Read the project's Makefile or docker-compose.yml to find the start/stop/shell commands, then add to projects.yaml:

  myproject:
    name: "My Project"
    description: "What it is"
    path: ~/Developer/myproject
    aliases: [mp]                          # short names for CLI
    services:
      default:
        description: "Stack summary"
        commands:
          up: "make start"                 # or: docker compose up -d
          down: "make stop"                # or: docker compose down
          build: "make build"              # optional
          init: "make setup"               # optional: first-time setup
          shell: "docker compose exec app bash"
          logs: "docker compose logs -f"
        container_filter:
          name: "myproject"                # prefix for `docker ps --filter name=`
        custom:                            # optional: project-specific commands
          migrate:
            command: "make migrate"
            description: "Run DB migrations"

Multi-service project (multiple repos / ordered startup)

For projects with separate sub-repos that share a Docker network:

  platform:
    name: "Platform"
    description: "Microservice platform"
    path: ~/Developer/platform
    type: multi-service
    network: platform-net                  # shared Docker network
    pre_up:
      - "docker network create platform-net 2>/dev/null || true"
    services:
      gateway:
        path: gateway-repo                 # relative to project path
        description: "Traefik"
        commands:
          up: "make up"
          down: "make down"
        order: 0                           # starts first
      api:
        path: api-repo
        description: "Core API"
        commands:
          up: "make up-{env}"              # {env} replaced with --env value
          down: "make down-{env}"
          shell: "docker compose exec app bash"
        order: 1                           # starts second
    default_env: local
    environments: [local, dev, stage, prod]

How to figure out the right commands

1. Check if there's a Makefile — look for targets like up, start, build, setup, shell
2. Check docker-compose.yml / compose.yml — note the service names and any -f file flags
3. For container_filter.name, run docker ps while the project is running and find the common prefix
4. For shell, check which container has the app runtime (usually app, php, php-fpm)

Config schema reference

Field	Type	Description
name	string	Display name
description	string	One-line description
path	string	Absolute path (supports ~)
repo	string	GitHub repo (owner/name) for pmt clone
aliases	string[]	Alternative CLI names
type	single-service | multi-service	Default: single
network	string	Shared Docker network name
pre_up	string[]	Commands to run before starting any service
pre_down	string[]	Commands to run after stopping all services
default_env	string	Default environment (for {env} substitution)
environments	string[]	Available environments
services.<key>
path	string	Path relative to project (or . for same dir)
repo	string	GitHub repo for this service (multi-service)
description	string	Service description
commands	Record	Map of command names to shell commands
container_filter	object	name, network, or compose_project for docker ps filtering
order	number	Startup order (lower = first, multi-service only)
custom	Record	Extra commands available via pmt run

Tech stack

Node.js + TypeScript. Ink (React for CLI) for the interactive dashboard. Commander.js for argument parsing.

License

MIT