CLI reference

Every stackspace verb, with arguments, flags, and behavior.

Global flags

--config — path to stackspace.yaml. Default: walk up from the current directory until found.

init

Scaffold a new stackspace workspace in the current directory (or in ./<name> if a name is passed). Writes stackspace.yaml and .gitignore. Refuses to overwrite either if they already exist. Does not run git init.

stackspace init [name] [-i | --interactive]

name (positional, optional) — if provided, scaffold into ./<name> instead of the current directory. The directory is created if missing; an error is raised if it exists and is non-empty.

-i, --interactive — prompt for workspace name, starter repos, and which checks to enable. Default: false.

add <owner>/<repo>

Register a new managed repo and clone it. Appends an entry to stackspace.yaml (preserving comments) and clones into ./repos/<name> via gh repo clone. Idempotent — if the repo name is already in config, the YAML edit is skipped but the clone is still attempted.

stackspace add <owner>/<repo>

stackspace add my-org/my-cli

clone

Clone any managed repos missing from the workspace. For each repo in stackspace.yaml: skip if already cloned, otherwise gh repo clone <url> repos/<name>. Idempotent.

stackspace clone

doctor

Verify all tools listed in stackspace.yaml are present. Runs every check (does not stop after the first failure) so the full picture is visible in one pass. Exits non-zero if any required check fails.

stackspace doctor

Output convention: ✓ = pass, ✗ = fail and required, ⚠ = fail and optional.

exec -- <command>...

Run a shell command in each managed repo. Joins all positional args (after --) into a single bash command and runs it in each repo's directory. Per-repo non-zero exits are reported in the summary but do not abort the loop.

stackspace exec -- <command>...

stackspace exec -- git log -1 --oneline
stackspace exec -- 'go test ./...'

fetch

Run git fetch --all --prune --quiet in each managed repo. Reports a per-repo ✓/✗ and a summary line; exits non-zero if any repo failed.

stackspace fetch

pull

Run git pull --ff-only in each managed repo. Per-repo failures are reported; exits non-zero if any failed.

stackspace pull

status

Print branch, ahead-behind vs upstream, and working-tree state per managed repo. Repos with no upstream show (no upstream); repos that aren't cloned are flagged.

stackspace status

branch

Print <repo>\t<branch> per managed repo, one per line, tab-separated. Useful for piping into other tools.

stackspace branch

update

Check for and install a new signed release. Fetches the manifest from the configured update channel, verifies the sha256 and ed25519 signature against the compiled-in trust list, and atomically replaces this binary.

stackspace update [--check] [--snapshot | --latest | --version <version>]

--check — only check; don't download or apply.

--snapshot — fetch from the snapshot channel.

--latest — fetch from the latest channel.

--version — pin to a specific version (e.g. v0.1.0).

--snapshot, --latest, and --version are mutually exclusive.