Getting Forge installed, configured, upgraded, and diagnosed in a repo. These are the bootstrap and maintenance commands — distinct from the everyday workflow stages.

Install & configure

forge setup                      # interactive agent configuration (Claude/Cursor/Codex …)
forge setup --yes                # non-interactive: accept defaults (use this in automation)
forge setup --agents claude,cursor --skip-external   # target specific harnesses, skip service prompts
forge setup --path <dir> --dry-run                   # preview against another dir, write nothing

forge setup is interactive by default. In any automated/agent context pass --yes (or --non-interactive) so it never blocks on a prompt.

Optional GitHub accounts per clone

Only when the user opts into multiple accounts: sign in once per account with native gh auth login, then select inside each intended clone:

forge github use <login>       # verify stored account/access before binding this clone
forge github status           # safe identity and transport diagnostics; --json supported
forge github run -- <harness>  # explicitly give a trusted child the selected GitHub identity
forge github unset            # remove this binding, not stored logins

Ordinary setup stays unbound. Never paste or persist tokens, automatically log in or switch accounts, or change Git author/remotes/SSH/helper configuration. Git transport is separate; HTTPS using gh auth git-credential can inherit the explicit child session's account. See the repository reference guide docs/reference/github-accounts.md for concurrent sessions and recovery.

Initialize a fresh repo

forge init --minimal             # shortcut for --profile minimal --yes
forge init --profile standard --harness claude,cursor
forge init --classification standard --dry-run       # preview the adoption config

forge init writes the Forge adoption config (.forge/config.yaml). The profile picks how much enforcement ships on: minimal (rails off) → standard → full. This configures the workflow; toggling an individual gate afterward is the gates skill.

Diagnose

forge doctor            # is the kernel DB on a cloud-synced / network path? (reliability signal)
forge doctor --json     # machine-readable

forge doctor is narrow: it reports the filesystem class of the Forge kernel database path (local / cloud-synced / network) so you can catch the reliability footgun of running the DB on OneDrive/Dropbox/a network share. It is not a general health check.

Upgrade readiness

forge upgrade --dry-run    # preview the planned self-heal, change nothing
forge upgrade              # apply safe self-heal steps to make the repo upgrade-ready

forge upgrade previews and applies safe self-heal steps for Forge's own state. It does not update the installed npm package — use your package manager for that.

Global hooks

forge hooks install --global                       # install native hooks for all harnesses
forge hooks install --global --harness codex       # scope to one harness (codex|hermes|all)
forge hooks install --global --dry-run             # preview

--global is the required consent flag — it opts you into installing hooks at the user level. (The other forge hooks subcommands — session-start, inbox-pickup, shepherd-events, memory-recall, capture — are machine-facing hook emitters the harness calls, not things you run by hand.)

Undo / redo the install

forge reset --soft --force     # remove .forge/ config only (keeps commands, rules, agents)
forge reset --hard --force     # remove ALL forge-managed files (keeps user-created files)
forge reinstall --force        # remove + re-run default setup in one step

reset and reinstall are destructive, so --force is required. reset with no --soft/--hard just prints usage.

Recommend tooling

forge recommend         # suggest tools/integrations for the current project

Boundaries

• Toggling a single gate/rail (e.g. TDD, kernel-tracking) is gates — init writes the initial config; gates flips one afterward.
• "Where am I / how is forge set up" in an already-configured repo is status / kernel, not setup.
• Installing project dependencies (bun install) is dev, not forge setup.