Configuration

The stackspace.yaml schema — single source of truth for a workspace.

stackspace finds the workspace by walking up from the current directory until it sees a stackspace.yaml. You can override that with --config <path> on any verb.

Schema

Two top-level keys, both sequences:

repos:
  - name: my-cli
    url: my-org/my-cli
  - name: my-daemon
    url: my-org/my-daemon

checks:
  - name: gh
    command: gh auth status
    required: true
  - name: git
    command: git --version
    required: true
  - name: go
    command: go version
    min_version: "1.25"
    required: true
  - name: docker
    command: docker --version
    required: false

repos

Each entry registers one managed repo. stackspace clones into ./repos/<name> from the workspace root.

name (string) — local directory name under repos/. Doesn't have to match the repo's GitHub name, but matching is the convention.

url (string) — passed to gh repo clone. Use <owner>/<repo> form (the GitHub CLI accepts this directly).

checks

Each entry declares one tool that stackspace doctor verifies. The check passes if command exits zero (and, if min_version is set, the version parsed from the command's stdout meets the floor).

name (string) — display name in doctor output.

command (string) — shell command to execute as the smoke test. Non-zero exit = fail.

min_version (string, optional) — semver-ish version floor. Parsed from the command's stdout; the check fails if the parsed version is below this.

required (bool) — true means a failure is reported as ✗ and doctor exits non-zero. false means a failure is reported as ⚠ and doctor still exits zero.

Editing the file

stackspace add edits stackspace.yaml in place using a YAML node round-trip that preserves comments and formatting. Hand-edits are also fine — stackspace clone reconciles whatever you put in there.