Getting started

Install Metastack and bring up a workspace in a few minutes.

Requirements

Install

Works on macOS (Apple Silicon and Intel) and Linux.

brew tap stackcube/tap
brew install metastack

Scaffold a workspace

From the directory you want to turn into a workspace:

metastack init

This writes metastack.yaml with an empty repos: list and a starter checks: set, plus a .gitignore that excludes repos/ (managed repos are clones, not tracked here). It does not run git init — track the workspace or don't, your call.

Pass a name to scaffold into a fresh subdirectory instead:

metastack init my-workspace

Or run interactively to be prompted for the workspace name, starter repos, and which checks to enable:

metastack init -i

Add repos

Each managed repo gets registered in metastack.yaml and cloned into ./repos/<name>:

metastack add my-org/my-cli
metastack add my-org/my-daemon

add appends to metastack.yaml (preserving comments) and clones via gh repo clone. It's idempotent — re-running with a name that's already registered skips the YAML edit but still tries the clone.

If you'd rather edit metastack.yaml by hand, do that and run:

metastack clone

clone reconciles the workspace with the config: any repo listed in metastack.yaml that isn't already cloned gets cloned. Idempotent.

Verify the toolchain

Run the checks declared in metastack.yaml to confirm contributors have the tools they need:

metastack doctor

Each check runs as a smoke command (e.g. gh auth status); a non-zero exit means the tool is missing or misconfigured. Required checks fail with ✗ and exit non-zero; optional checks fail with ⚠ and don't.

Daily ops

Once the workspace is set up, the rest of the verbs apply across every managed repo:

# Show branch / ahead-behind / working-tree state per repo
metastack status

# git pull --ff-only in every repo
metastack pull

# git fetch --all --prune in every repo
metastack fetch

# Run an arbitrary shell command in every repo
metastack exec -- git log -1 --oneline

# Create + checkout the same branch in every repo
metastack branch feat/billing

# Bump each repo's latest vX.Y.Z tag (patch/minor/major; --push to publish)
metastack tag minor

# Detach every repo onto a semver tag (latest by default; per-repo <= fallback)
metastack checkout list
metastack checkout v0.2.0

exec joins everything after -- into a single bash command. Per-repo non-zero exits are reported in the summary but don't abort the loop.

Where to go next