groot CLI specification

Status: normative contract. init shipped in v0.2; add and doctor in v0.3; init --preset in v0.4. Changes to this document are semver-relevant — stability.md defines exactly which surfaces are covered and the change rules (binding since v1.0.0).

Invocation forms

The npm package requires Bun ≥ 1.2 on the invoking machine. The compiled binary embeds its own runtime, but scaffolded workspaces still require Bun — groot checks and reports this in preflight.

groot init [dir]

Plant a new workspace. Interactive by default; fully scriptable with flags.

Flags

Defaults (--yes with no selection flags)

--web next --mobile none --api none --backend convex — a Next.js app wired to a Convex backend: groot's flagship pairing.

GitHub publishing

--github runs after verify's initial commit: Bun.which("gh") → gh auth status → gh repo create <name> --private|--public --source=. --remote=origin --push (every flag verified against the published gh sources and the 2.96.0 binary; non-interactive gh repo create requires exactly one visibility flag, and --push hard-errors on a repo with zero commits).

• Hard preconditions, checked before anything is generated — dry runs included (usage errors, exit 2): --github conflicts with --no-git, --public requires --github, a git identity (user.name + user.email) must exist, resolved as the new repository would see it — global/system config; a caller repo's local identity doesn't carry into the fresh git init, so it doesn't count — and the target must not already be a git repository: verify only inits and commits repos it creates, so with a pre-existing .git the generated workspace would sit uncommitted while --push shipped the old history (and committing into a user's repo uninvited would sweep up state that isn't groot's). The hint prints the manual plant-then-publish path.
• Everything after generation degrades, never fails: gh absent from PATH, gh unauthenticated (gh auth status exits 1), or a failed create (unauthenticated gh repo create exits 4) each print the reason plus the manual commands (gh auth login, the exact gh repo create … invocation) as next steps — the workspace is already valid, so the run exits 0.

Presets

--preset <path> reads an existing groot.json — a file, or a workspace directory containing one — as the selections source: groot init my-app --preset ../flagship replicates the shape of the workspace that manifest describes.

• Only the slot → framework shape is read. Workspace name, destination paths, ports, generator pins, conventions, and createdWith always come from the current CLI — a preset written by an older groot never pins stale generators.
• Explicit slot flags win over the preset; slots absent from the preset resolve to none. With a target directory given, a preset run is fully non-interactive.
• The preset is validated like any workspace manifest — unknown framework ids or manifest versions are rejected with exit 2.
• A manifest that grew multiple scaffolds into one slot (via groot add --path) presets the first one per slot and warns about the rest — replicate them with groot add --path afterwards.

Interactive flow

Prompts (clack) run only for slots not already fixed by flags — mixing flags and prompts is supported. Prompt order: web → mobile → api → backend → confirm plan. Ctrl-C at any prompt exits with code 130 and writes nothing.

Output contract

• Human mode: staged progress (plant → grow per app → stitch → verify) with a final "next steps" block (e.g. the deferred bunx convex dev login step when Convex is selected).
• --dry-run --json emits the plan (schema below) and exits 0. Nothing else is written to stdout in --json mode; diagnostics go to stderr.

Exit codes

groot add <scaffold> (v0.3)

Grow an existing groot workspace: groot add expo, groot add hono, groot add sveltekit --path apps/marketing.

Runs the same grow → stitch → verify stages as init for just the new scaffold — no trunk is re-planted. Because every stitch operation is idempotent over the existing scaffolds, cross-cutting wiring lands automatically: adding convex links the existing web/mobile apps to the backend, and adding a frontend next to an existing backend wires the new app the same way. The stitch stage persists the updated groot.json.

Flags

Rules

• Requires a groot.json manifest (written by init) — add walks up from the current directory to find the workspace root. Relative --path values resolve against that root, not the current directory.
• Occupancy: a scaffold whose slot is already filled is refused (exit 2) unless --path targets a fresh directory. Path equality with any existing scaffold is always refused. The backend slot is single-occupancy — its package name (@repo/backend) is fixed by the workspace conventions, so --path is no escape hatch there.
• Ports: a dev-port collision with an existing scaffold (e.g. growing Hono next to Elysia — both default to 3001) is a warning, not an error; groot doctor flags it persistently until one port is changed.
• Provenance: groot.json's createdWith keeps its original value — it records which CLI planted the workspace, not which one last grew it.
• Git: add never runs git init — the workspace keeps whatever git state it has, including none. Any .git a generator initializes inside the new scaffold is removed after the grow (the workspace root owns git history); a .git that pre-existed the grow is preserved. init applies the same rule to every scaffold it grows.
• Targeted rollback: if the generator fails, only the new scaffold directory is removed (--keep-failed keeps it for inspection); the rest of the workspace is never touched. Stitch/verify failures leave the tree in place, as in init.
• Machine output: --dry-run --json emits the manifest as groot.json would read after the add — the same versioned schema init --dry-run --json emits, with the new scaffold as the final entry. Stdout carries only the manifest; diagnostics and warnings go to stderr, per the output contract.

Exit codes

Same table as init: 2 invalid arguments and occupancy violations, 4 generator failure, 5 stitch/verify failure.

groot doctor (v0.3)

Verify workspace health: workspace globs valid, single lockfile, no port collisions, per-scaffold checks from each adapter (e.g. convex/_generated in sync), bun version, turbo tasks resolvable. Exits 0 (healthy) or 5 (problems found, each with a suggested fix). --json emits structured results.

groot.json manifest

Written to the workspace root by init, updated by add. The manifest is groot's memory — never required by the apps themselves at runtime.

{
  "$schema": "https://raw.githubusercontent.com/bloxy-studios/groot/main/schemas/groot.schema.json",
  "version": 1,                      // manifest schema version
  "createdWith": "create-groot@0.2.0",
  "conventions": {
    "packagesNamespace": "@repo"
  },
  "scaffolds": [
    {
      "slot": "web",
      "framework": "next",
      "path": "apps/web",
      "generator": "create-next-app@16",   // pinned major actually used
      "port": 3000
    },
    {
      "slot": "backend",
      "framework": "convex",
      "path": "packages/backend",
      "generator": null,                   // groot wrote these files directly
      "port": null
    }
  ]
}

Non-interactive contract (CI & agents)

groot treats scriptability as a first-class feature:

1. Any run where every slot is fixed by flags (or a --preset) and --yes is present must complete with zero prompts, or exit non-zero — it must never hang waiting for input.
2. --dry-run --json (on init and add) is stable, versioned output (the manifest schema) — safe for agents to parse; doctor --json emits its structured results the same way.
3. Progress output is plain and line-based everywhere — groot has no spinners to garble CI logs. --verbose additionally streams full generator output.
4. Anything interactive that cannot be avoided (today: Convex login) is never run by groot — it is printed as a next step instead.

Recipes for CI systems and agents live in ci.md.