ComposeCat

ComposeCat is a lightweight CLI that builds and runs Docker or Podman Compose commands from your terminal.

Use it exactly like your usual compose binary—just start with compose-cat instead of docker compose, podman compose, docker-compose, or podman-compose.

Highlights

• Compose binary auto-detection – Probes docker compose, podman compose, docker-compose, and podman-compose (override or reorder via --cmp-bin or CMPCAT_COMPOSE_BIN).
• Dotenv layering & profiles – Always loads .env, .env.local, and, when profiles are provided, .env.<PROFILE>/.env.<PROFILE>.local unless --disable-profile-based-dotenv is supplied.
• COMPOSE_* priming – Values detected in dotenv files automatically populate COMPOSE_* variables (e.g., COMPOSE_PROJECT_NAME, COMPOSE_FILE, COMPOSE_PROFILES) before the compose command runs.
• Cleanup helpers – cmp-clean, cmp-clean-i-local, and cmp-clean-i-all encapsulate common teardown flows.
• Pluggable hooks – Run pre/post scripts with per-command, per-platform, and per-binary variants to enforce custom workflows.

Quick Start

Install globally with npm:

npm install -g compose-cat

Add as a devDependency inside a project:

npm install --save-dev compose-cat

Run ad-hoc with npx:

npx compose-cat <COMPOSE_COMMAND> [ARGS]

Examples:

compose-cat <COMPOSE_COMMAND> [ARGS]
compose-cat up -d
compose-cat down

CLI Options

• --cmp-hook <value...>: Hook names to run (pre and post). Example: --cmp-hook up runs matching cmp.pre.up.* and cmp.post.up.* hooks.
• --cmp-bin <value...>: Provide compose binary candidates in priority order.
  • Example: --cmp-bin "podman compose" --cmp-bin "docker compose".
  • Also configurable via CMPCAT_COMPOSE_BIN.
• --cmp-prefix <value>: Set the ComposeCat environment variable prefix (default: CMPCAT_).
  • Also configurable via CMPCAT_ARG_PREFIX.
• --cmp-dotenv-prefix <value>: Set the dotenv file prefix to detect (default: .env).
  • Also configurable via CMPCAT_ARG_DOTENV_PREFIX.
• -p, --project-name <value>: Compose project name (overrides COMPOSE_PROJECT_NAME).
• --profile <value...>: Profiles to use (comma-separated or repeat the flag), e.g., --profile dev or --profile dev,test.
• --disable-profile-based-dotenv: Skip loading .env.<PROFILE> and .env.<PROFILE>.local files even when profiles are provided.

Commands

• cmp-clean: Convenience cleanup. Removes containers and networks/volumes.

  • ${CMPCAT_DETECTED_COMPOSE_BIN} rm -fsv
  • ${CMPCAT_DETECTED_COMPOSE_BIN} down --volumes

• cmp-clean-i-local: Like cmp-clean, but also removes images referenced by services that do not have a custom tag.

  • ${CMPCAT_DETECTED_COMPOSE_BIN} rm -fsv
  • ${CMPCAT_DETECTED_COMPOSE_BIN} down --rmi local --volumes

• cmp-clean-i-all: Like cmp-clean, but also removes every image referenced by the services.

  • ${CMPCAT_DETECTED_COMPOSE_BIN} rm -fsv
  • ${CMPCAT_DETECTED_COMPOSE_BIN} down --rmi all --volumes

Caution:

Pass ComposeCat options (such as --profile or -p) immediately after the built-in command. For example: compose-cat cmp-clean --profile main -p my-project.

How It Works

1. Read CLI options, including profiles, project name, prefix overrides, and dotenv preferences.
2. Determine the environment variable prefix from --cmp-prefix or CMPCAT_ARG_PREFIX (default: CMPCAT_).
3. Determine the dotenv prefix from --cmp-dotenv-prefix or CMPCAT_ARG_DOTENV_PREFIX (default: .env).
4. Load base dotenv files (.env, .env.local). If profile-based detection is enabled, also load .env.<PROFILE> and .env.<PROFILE>.local for each CLI profile.
5. Detect the compose binary from CMPCAT_COMPOSE_BIN (if set) or probe defaults; override the order with --cmp-bin.
6. Prime COMPOSE_* environment variables with any values discovered in dotenv files.
7. Build the compose command: add --env-file flags, --profile flags, and -p/--project-name when provided.
8. Run matching pre-hooks.
9. Execute the compose command and capture its exit code.
10. Run matching post-hooks and exit with the final status code.

Special Flow for Cleanup Commands

Cleanup commands follow the general flow, but expand to multiple compose commands executed in sequence (see “Commands” above for exact arguments).

ComposeCat Environment Variables (Consumed at Startup)

Configure these environment variables to control detection and defaults.

CMPCAT_ARG_PREFIX

• Sets the prefix for all ComposeCat-related environment variables.
• Default: CMPCAT_
• Example: CMPCAT_ARG_PREFIX=MyPrefix_ yields variables like MyPrefix_COMPOSE_BIN instead of CMPCAT_COMPOSE_BIN.

CMPCAT_ARG_DOTENV_PREFIX

• Sets the dotenv file prefix used for detection.
• Default: .env

ComposeCat Environment Variables (Applied During Execution)

All variables in this section use the active prefix (default CMPCAT_).

CMPCAT_COMPOSE_BIN

• Comma-separated list of compose binaries to probe, in order.
• If unset, ComposeCat probes in this order: docker compose, podman compose, docker-compose, podman-compose.
• Examples:
  • CMPCAT_COMPOSE_BIN=docker compose
  • CMPCAT_COMPOSE_BIN=podman compose
  • CMPCAT_COMPOSE_BIN=podman compose,docker compose

Environment Variables Set by ComposeCat

Set by ComposeCat for runtime configuration and profile management.

CMPCAT_DETECTED_COMPOSE_BIN

• The compose binary selected at runtime.

CMPCAT_PROFILES

• The list of active profiles joined by commas, e.g., main,sub_1.
• Empty when no profile is selected via CLI options.

CMPCAT_PROFILE_<N>

• The active profile at index N (1-based), e.g., CMPCAT_PROFILE_1=main.
• Cleared when no profiles are active so stale values do not persist between runs.

Dotenv Auto-Detection

ComposeCat discovers dotenv files at startup and adds them to the compose command as --env-file flags.

The following files are considered when present:

• Base files:

  • .env
  • .env.local

• Profile files (each <PROFILE> comes from --profile, unless --disable-profile-based-dotenv is used):

  • .env.<PROFILE>
  • .env.<PROFILE>.local

The dotenv file prefix is configurable via --cmp-dotenv-prefix or CMPCAT_ARG_DOTENV_PREFIX.

Hooks

Hook scripts can run before and after the compose command. ComposeCat searches for hook files in the current working directory and supports per-command, per-platform, and per-binary variants.

File name patterns (where stage is pre or post):

• Base: cmp.<stage>.<EXT>
• Platform: cmp.<stage>.<PLATFORM>.<EXT>
• Binary: cmp.<stage>.+<BINARY>.<EXT>
• Platform + Binary: cmp.<stage>.<PLATFORM>+<BINARY>.<EXT>
• Hook name: cmp.<stage>.<HOOK>.<EXT>
• Hook name + Platform/Binary: cmp.<stage>.<HOOK>.<PLATFORM>+<BINARY>.<EXT>

Where:

• HOOK: Name provided via the --cmp-hook argument (e.g., up).
• PLATFORM: Target platform. Use win32 or windows for Windows, darwin or macos for macOS, and linux for Linux.
• BINARY: Executable used to run the script (e.g., bash, sh, pwsh, node). If omitted, the file itself is executed. Ensure it is executable or includes a shebang.
• EXT: File extension (e.g., sh, ps1, js).

Examples when running with --cmp-hook=up (if present, these may execute):

• cmp.pre.sh
• cmp.pre.linux.sh
• cmp.pre.darwin.sh
• cmp.pre.win32.ps1
• cmp.pre.win32+pwsh.ps1
• cmp.pre.+node.js
• cmp.pre.up.sh
• cmp.pre.up.linux.sh
• cmp.pre.up.darwin.sh
• cmp.pre.up.win32.ps1
• cmp.pre.up.win32+pwsh.ps1
• cmp.pre.up.+node.js
• cmp.post.sh
• cmp.post.linux.sh
• cmp.post.darwin.sh
• cmp.post.win32.ps1
• cmp.post.win32+pwsh.ps1
• cmp.post.+node.js
• cmp.post.up.sh
• cmp.post.up.linux.sh
• cmp.post.up.darwin.sh
• cmp.post.up.win32.ps1
• cmp.post.up.win32+pwsh.ps1
• cmp.post.up.+node.js

Environment variables exposed to hooks:

• CMPCAT_HOOK_EVENT: Stage (pre or post).
• CMPCAT_HOOK_COMMAND: Hook name when --cmp-hook is provided; otherwise empty.
• CMPCAT_HOOK_PLATFORM: Matched platform string, if any.
• CMPCAT_HOOK_BINARY: Matched binary string, if any.
• CMPCAT_HOOK_FILE: Absolute path of the hook file being executed.

Notes

• You don’t need -- to pass through arguments; the CLI forwards unknown options and positional arguments to the underlying compose command.