Getting started

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

Requirements

Install

brew tap stackcube/tap
brew install stackspace

Scaffold a workspace

From the directory you want to turn into a workspace:

stackspace init

This writes stackspace.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:

stackspace init my-workspace

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

stackspace init -i

Add repos

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

stackspace add my-org/my-cli
stackspace add my-org/my-daemon

add appends to stackspace.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 stackspace.yaml by hand, do that and run:

stackspace clone

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

Verify the toolchain

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

stackspace 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
stackspace status

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

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

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

# TSV output of 
stackspace branch

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