Getting started

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

Requirements

Install

Homebrew, on macOS (Apple Silicon and Intel) and Linux:

brew install stackcube/tap/metastack

Without Homebrew, the one-liner downloads the signed release for your platform, checks its sha256 and (where openssl can do ed25519) its signature, and puts the binary in ~/.local/bin. No sudo.

curl -fsSL https://stackcube.dev/install/metastack | sh

Pin a version or change the destination by setting the variable on the sh side of the pipe:

curl -fsSL https://stackcube.dev/install/metastack | METASTACK_VERSION=v0.4.0 sh
curl -fsSL https://stackcube.dev/install/metastack | METASTACK_INSTALL_DIR=/usr/local/bin sh

Or download the signed binary directly from https://updates.stackcube.dev/metastack/<version>/metastack-<os>-<arch> (darwin-arm64, darwin-amd64, linux-amd64, linux-arm64).

However you installed it, metastack update keeps it current; for Homebrew installs it defers to brew upgrade.

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, clone provider, 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 with the configured provider (gh unless you set otherwise). 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