Command reference¶

Every command of gdd, with its options, as gdd <command> --help prints them.

Note

Generated by scripts/make_reference.py from gdd 0.1.0. Do not edit this page: change the help text in the code and run the script again.

Run gdd with no arguments in a terminal to open the Board. In a project, use bin/gdd: it runs the gdd built for that project.

Set up a project: init · bootstrap · adopt · agents · stacks · upgrade

Plan and approve: new-change · classify · gate · sitting · note · changelog-line

Build and release: launch · resume · park · prepare · merge · release

Gates and checks: g2 · g3 · guard · snapshot · scope · selftest · ci

See where things stand: status · board · inbox · report · learn · changelog · session

Set up a project¶

gdd init¶

Sets up GDD in this folder, which becomes the project root: the harness (gdd/, bin/gdd, the CI workflow), the Brief, the agents' commands, AGENTS.md and CLAUDE.md when absent, the skeleton of each stack the folder has no project of, and the lines of each stack and .gdd/ in .gitignore; then commits what it wrote, and only that. Never overwrites a file, refuses inside a GDD project and installs nothing (gdd bootstrap does)

Usage: gdd init [OPTIONS]

Options:
      --name <NAME>...                The name of the project
      --platform <PLATFORM>           Where it runs [possible values: mobile, desktop, web, cli, other]
      --stack <STACKS>...             Its stacks (gdd stacks lists them)
      --agents <AGENTS>...            Its coding agents, the first builds; without it, those on the PATH (claude, codex, opencode)
      --language <LANGUAGE>           The language the agents use with the human [default: en]
      --description <DESCRIPTION>...  What it is, in words
      --sensitive <sensitive>...      What would be serious if it failed: one area each time
      --accept-same-family            Accept a Reviewer of the Builder's model family when every agent is of one family
  -h, --help                          Print help

gdd bootstrap¶

The first install of each stack of gdd/project.toml, in order, which writes its lock file: stops at the first that fails, then commits the files of the stacks' supply chain the run created or changed, and nothing else. Run it once, after gdd init

Usage: gdd bootstrap

Options:
  -h, --help  Print help

gdd adopt¶

Adopts a project that already has code: runs once each G2 and G3 command that judges the whole project (not acceptance, mutation or secrets*), keeps what each failing one said in .gdd/adoption/, records them as known debt in gdd/debt.toml, which it commits alone, and proposes a Refactor per command, riskiest first. Refused once gdd/debt.toml exists

Usage: gdd adopt

Options:
  -h, --help  Print help

gdd agents¶

The GDD commands, and the instructions of each stack in stack of gdd/project.toml, in the folders of the coding agents (claude, codex, opencode), as their agent sheets say

Usage: gdd agents <COMMAND>

Commands:
  install  Writes every GDD command and the instructions of each stack of the project for each agent, and no other file. Prints the paths as JSON
  check    Checks that each GDD command and the instructions of each stack of the project of each agent are exactly what install writes; names every file missing or edited, and exits with 1
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

gdd agents install¶

Writes every GDD command and the instructions of each stack of the project for each agent, and no other file. Prints the paths as JSON

Usage: gdd agents install [OPTIONS]

Options:
      --agent <AGENTS>...  The agents; without it, the integrations of gdd/models.toml
  -h, --help               Print help

gdd agents check¶

Checks that each GDD command and the instructions of each stack of the project of each agent are exactly what install writes; names every file missing or edited, and exits with 1

Usage: gdd agents check [OPTIONS]

Options:
      --agent <AGENTS>...  The agents; without it, the integrations of gdd/models.toml
  -h, --help               Print help

gdd stacks¶

The stack sheets gdd comes with (python, rust, typescript): one line per sheet

Usage: gdd stacks [COMMAND]

Commands:
  show     One sheet: the tool for each need, the commands and the protected paths
  compose  What the named sheets give together, as TOML: the shape of gdd/commands.toml plus a [protected] table. Writes nothing
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

gdd stacks show¶

One sheet: the tool for each need, the commands and the protected paths

Usage: gdd stacks show <NAME>

Arguments:
  <NAME>  The stack

Options:
  -h, --help  Print help

gdd stacks compose¶

What the named sheets give together, as TOML: the shape of gdd/commands.toml plus a [protected] table. Writes nothing

Usage: gdd stacks compose [NAMES]...

Arguments:
  [NAMES]...  The stacks; a name given twice counts once

Options:
  -h, --help  Print help

gdd upgrade¶

Proposes what this gdd writes of the files gdd init wrote once (gdd/generated.toml lists them) on the branch gdd-upgrade, merged three ways with what the project made of them: first what this gdd writes, then the merge, with the lines both changed marked as conflicts. Runs on the main branch with everything committed; nothing on it changes and nothing is pushed. Builders and Reviewers cannot run it

Usage: gdd upgrade

Options:
  -h, --help  Print help

Plan and approve¶

gdd new-change¶

Creates a change: its record and, when it has none, its branch change/ from the main branch. Logs it and prints its classification as JSON

Usage: gdd new-change [OPTIONS] --title <TITLE> <CHANGE>

Arguments:
  <CHANGE>  Id of the change: lowercase letters, digits and hyphens

Options:
      --title <TITLE>          What the change is about, in a few words
      --type <KIND>            The kind of work [default: Feature] [possible values: Feature, Hotfix, Refactor, Migration, Spike, No-code]
      --paths [<PATHS>...]     Paths the change plans to touch; patterns are allowed
      --resumable              The change can be resumed after an interruption (a condition of the fast lane)
      --min-color <MIN_COLOR>  Declared minimum color: it raises the color, never lowers it
      --option <OPTION>        One variant of a Spike for this option of its question; once for each option (2 to 4)
      --variants <N>           That many variants of a Spike on the same brief (2 to 4)
  -h, --help                   Print help

gdd classify¶

Color, lane and gates of a change, from its plan and what it touched, as JSON

Usage: gdd classify [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
  -h, --help  Print help

gdd gate¶

Records a gate decision: G0 (by the machines), the red zones (by a human), or the plan, G1, G2, G3 or G4 of a change. Approving G1 seals the scenario files of the change. Builders and Reviewers cannot record anything

Usage: gdd gate [OPTIONS] <GATE> <DECISION> [CHANGE]

Arguments:
  <GATE>      The gate [possible values: G0, zones, plan, G1, G2, G3, G4]
  <DECISION>  ok or ko; approve and reject say the same
  [CHANGE]    Id of the change, for the plan, G1, G2, G3 and G4

Options:
      --by <BY>      Who decides: human or machines [default: human]
      --note <NOTE>  What to read about the decision [default: ""]
  -h, --help         Print help

gdd sitting¶

The sitting of a change on a screen, in a terminal: the scenarios of its branch, the red zones and the plan, to approve (G1, the red zones, the plan) or to ask for changes (G1 KO). Nothing is written before the human confirms

Usage: gdd sitting <CHANGE>

Arguments:
  <CHANGE>  Id of the change (its record is .gdd/changes/<id>/change.json)

Options:
  -h, --help  Print help

gdd note¶

Leaves a note on a change for its Decision Inbox

Usage: gdd note <CHANGE> <KIND> <TEXT>...

Arguments:
  <CHANGE>   Id of the change: its record is .gdd/changes/<id>/change.json
  <KIND>     needs (a decision for the human), decided (taken without them) or parked [possible values: needs, decided, parked]
  <TEXT>...  What the note says; its words are joined with single spaces

Options:
  -h, --help  Print help

gdd changelog-line¶

Sets the line of a change in the changelog, which its merge commit carries as trailers: a section of Keep a Changelog and its words, or --none to leave the change out. Without one, the title goes under the section of its type (Feature: Added, Hotfix: Fixed, Migration: Changed), and the other types are left out. Builders and Reviewers cannot set it

Usage: gdd changelog-line [OPTIONS] <CHANGE> [SECTION] [LINE]...

Arguments:
  <CHANGE>   Id of the change: its record is .gdd/changes/<id>/change.json
  [SECTION]  The section: Added, Changed, Deprecated, Removed, Fixed or Security
  [LINE]...  The line, for the people who use the project; its words are joined with single spaces

Options:
      --breaking  The change breaks what worked before
      --none      Leave the change out of the changelog
  -h, --help      Print help

Build and release¶

gdd launch¶

Runs the recipe of a change in its own git worktree, on its branch change/, while this checkout goes to the main branch: Build, G2, G3, the Reviewer, merge and pre; then it waits for the human G4 when the change needs it, or goes to production. The worktree goes when the change closes. Refuses uncommitted changes outside that branch, and a change past [parallel] max of gdd/rules.toml changes building. Next to a change in flight whose planned paths overlap its own, it warns first, also in its Decision Inbox: git settles the overlap when the change merges. A change that parks exits with 1

Usage: gdd launch <CHANGE>

Arguments:
  <CHANGE>  Id of the change: its record is .gdd/changes/<id>/change.json

Options:
  -h, --help  Print help

gdd resume¶

Answers the G4 of a change paused at it: ok takes it to production, ko rejects it, and polish runs one more Builder round with your notes and pauses at G4 again. Builders and Reviewers cannot answer

Usage: gdd resume [OPTIONS] --g4 <G4> <CHANGE>

Arguments:
  <CHANGE>  Id of the change: its record is .gdd/changes/<id>/change.json

Options:
      --g4 <G4>         The answer to G4 [possible values: ok, ko, polish]
      --note <NOTE>...  What to read about the answer: the rest of the words. Polish needs it
      --variant <N>     The variant of a Spike with variants that OK brings to main, or that polish builds again
  -h, --help            Print help

gdd park¶

Parks a change: stops it with a message for the human in its Decision Inbox. Always exits with 1

Usage: gdd park <CHANGE> <REASON>...

Arguments:
  <CHANGE>     Id of the change: its record is .gdd/changes/<id>/change.json
  <REASON>...  Why; its words are joined with single spaces

Options:
  -h, --help  Print help

gdd prepare¶

Checks that a change may enter Build (G0, red zones, G1, plan, model families, its branch) and starts it. Prints its decision, with the model of each role, as JSON

Usage: gdd prepare [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
  -h, --help  Print help

gdd merge¶

Merges a change whose G3 is open into the main branch, with its record in the merge commit, then builds the artifact and deploys it to pre. Prints the deploy as JSON

Usage: gdd merge [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
  -h, --help  Print help

gdd release¶

A release step of gdd/commands.toml: pre (tests and demo), promote (to production, after G4) or observe (rolls the change back when production gets worse). Prints it as JSON. In [versions] mode = "auto" of gdd/rules.toml (the default), promote gives a change with a changelog line the next v version, in GDD_VERSION, and releases it once it passed. Without a step: the next version of what main merged since its newest tag, and its lines; --yes releases it, in any mode (CHANGELOG.md, when main tracks one, in a commit of its own, and the tag), and --version chooses it. Builders and Reviewers cannot release

Usage: gdd release [OPTIONS] [STEP] [CHANGE]

Arguments:
  [STEP]    The step; without one, the next version of what is merged [possible values: pre, promote, observe]
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
      --yes              Release the next version, without asking
      --version <X.Y.Z>  The version to release instead of the next one, after the newest: x.y.z
  -h, --help             Print help

Gates and checks¶

gdd g2¶

Loop Gate: the G2 commands of gdd/commands.toml, Path Guard and, in build mode, the scope. Saves the result next to the change, logs it unless an agent runs it (GDD_ROLE) and prints it as JSON

Usage: gdd g2 [OPTIONS] [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
      --role <ROLE>  Role Path Guard judges (builder-build also gets the scope check) [default: builder]
      --strict       Exit with code 1 when the gate fails
  -h, --help         Print help

gdd g3¶

Merge Gate: the G3 commands of gdd/commands.toml, Path Guard and the scenario count. Saves the result next to the change, logs it unless an agent runs it (GDD_ROLE) and prints it as JSON

Usage: gdd g3 [OPTIONS] [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
      --role <ROLE>  Role Path Guard judges (builder-build also gets the scope check) [default: builder]
      --strict       Exit with code 1 when the gate fails
  -h, --help         Print help

gdd guard¶

Path Guard: what a change touched since its build started that a role must not touch, as JSON

Usage: gdd guard [OPTIONS] [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
      --role <ROLE>     Role whose protected paths count (builder-build, builder-test, reviewer...) [default: builder]
      --strict          Exit with code 1 when Path Guard fails
      --since-snapshot  Count only what changed since the last `gdd snapshot`
  -h, --help            Print help

gdd snapshot¶

Records what a change touched as it is now, so gdd guard --since-snapshot judges only what changes after

Usage: gdd snapshot [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
  -h, --help  Print help

gdd scope¶

Paths a change touched outside its plan: accepted when their color is not higher than the change's, as JSON

Usage: gdd scope <CHANGE>

Arguments:
  <CHANGE>  Id of the change: its record is .gdd/changes/<id>/change.json

Options:
  -h, --help  Print help

gdd selftest¶

Harness self-test: a failing test turns a green G2 red, the harness is protected and CI runs the gates, rollback works in pre, and zero scenarios fail G3. Saved in .gdd/selftest.json and logged; exits with 1 unless all four pass

Usage: gdd selftest

Options:
  -h, --help  Print help

gdd ci¶

What CI runs: on the branch change/ (GITHUB_HEAD_REF, else the current one), no harness path changed against the main branch, and G2 and G3 green. Reads and writes nothing under .gdd/; exits with 1 when CI fails

Usage: gdd ci

Options:
  -h, --help  Print help

See where things stand¶

gdd status¶

Where the project stands: G0, red zones, self-test, scenarios, changes and log

Usage: gdd status

Options:
  -h, --help  Print help

gdd board¶

The changes of the project by phase on a screen (Discover, Build, Release, Done), in a terminal. Read-only: nothing on it writes anything

Usage: gdd board

Options:
  -h, --help  Print help

gdd inbox¶

The Decision Inbox of a change: what is open for the human. Also saved in .gdd/changes//inbox.md

Usage: gdd inbox [CHANGE]

Arguments:
  [CHANGE]  Id of the change (its record is .gdd/changes/<id>/change.json); else GDD_CHANGE

Options:
  -h, --help  Print help

gdd report¶

Tokens, cost and time of the agent calls in the log; with --time, where the time of each change goes: active (agents, gates, release), waiting and between steps

Usage: gdd report [OPTIONS]

Options:
      --by <BY>          Fields to group the calls by, separated by commas (change, phase, model, role, agent...) [default: role]
      --change <CHANGE>  Count only the records of this change
      --json             Print the groups, or the changes with --time, as a JSON list; with --dora, one object
      --time             Where the time of each change goes, from its first line in the log to its last, instead of the agent calls; without --change, the project adds every change up
      --dora             DORA's five delivery metrics and GDD's signals, from the log and the records of the changes, instead of the agent calls
      --since <SINCE>    With --time or --dora, only the changes created on or after this day, YYYY-MM-DD (UTC)
  -h, --help             Print help

gdd learn¶

Learn: runs the Learn tools of gdd/commands.toml ([learn]: warnings, never a gate), keeps what each one said in .gdd/learn/ and lists the polish notes the human gave at G4, to spot the ones that repeat, and the classes of finding that repeat in the Reviewer's reviews. Exits with 0 whatever the tools found

Usage: gdd learn [OPTIONS]

Options:
      --since <SINCE>  Only the notes and reviews of the changes created on or after this day, YYYY-MM-DD (UTC)
  -h, --help           Print help

gdd changelog¶

Shows what CHANGELOG.md lacks of the lines the commits of the main branch carry (what no v tag released yet goes under Unreleased), and with --write adds only that, each line with a comment naming its commit. Every word of the file stays; nothing is committed. In a terminal it asks before it writes

Usage: gdd changelog [OPTIONS]

Options:
      --write  Add what is missing to CHANGELOG.md, without asking
      --check  Fail when something is missing, for CI; writes nothing
  -h, --help   Print help

gdd session¶

Adds the requests of the interactive Claude Code sessions of the project to the log, one line per model and each request once; the sessions gdd started for its agents are left out

Usage: gdd session [OPTIONS] --phase <PHASE>

Options:
      --phase <PHASE>    The phase of the method the conversation belongs to [possible values: 0-setup, 1-discover, 2-build, 3-integrate, 4-release, 5-learn]
      --change <CHANGE>  Count it for this change
  -h, --help             Print help