The FlowForge command-line surface has two halves. Slash commands (/flowforge:session:start, /flowforge:dev:status, and dozens more) are the primary way you interact with FlowForge from inside Claude Code: the hook runtime resolves each slash command to a markdown file under commands/flowforge/, extracts its bash body, and runs it. The flowforge Go binary is a small companion CLI that exposes a handful of subcommands (install, register-repo, tui, run, version, migrate, upgrade, plus the internal worker) so the same workflows are available outside Claude Code — from CI, makefiles, scripts, and shell aliases.
You typically pick which surface to use based on context. Inside Claude Code you write the slash form (/flowforge:dev:status). Outside, you invoke the binary (flowforge run flowforge:dev:status) — the resolution rules are identical, so a slash command and its flowforge run counterpart do exactly the same work in the same project.
Every slash command lives under commands/flowforge/<namespace>/<leaf>.md. The namespace organizes commands by the workflow surface they belong to: session for session ceremony, dev for day-to-day development, project for project-shape commands, and so on. The catalog below is regenerated from the source markdown’s frontmatter via v3/site/scripts/gen-cli-reference.mjs; manual edits inside the AUTOGEN markers are overwritten on the next run.
To regenerate after editing a command’s frontmatter:
Terminal window
nodev3/site/scripts/gen-cli-reference.mjs
62 slash commands across 17 namespaces. Sourced from commands/flowforge/**/*.md frontmatter.
The flowforge binary is built from v3/cmd/flowforge/. Several subcommands are exposed today; one of them (worker) is hidden from --help output because it is invoked only by the controller. The binary has no runtime dependencies — no Node.js, no npx, no language toolchain. It is a single Go executable.
Bootstraps the FlowForge asset bundle at ~/.flowforge/ (or $FLOWFORGE_HOME). Run once per machine. The asset directories (agents/, commands/, hooks-templates/, scripts/, templates/, bin/, docs/, documentation/) are fully overwritten on each run so stale entries cannot survive an upgrade; user state files (config.json, repos/index.json) are preserved across runs. The --global flag is mandatory in v1.0. See flowforge install --global.
Registers a git repository with the global install so per-repo session and billing state has a home under ~/.flowforge/repos/<repo-id>/. The registered worktree itself is never modified. Accepts an optional positional path argument (defaults to the current directory). See flowforge register-repo.
Launches the full-screen Bubble Tea controller inside tmux. Requires the calling shell to be inside a tmux session (TMUX must be set). Takes a required --project flag and an optional --session flag. See flowforge tui.
Executes any FlowForge slash command from its markdown definition. Walks up to find the project root, resolves the colon-separated command id to a markdown file, extracts the bash blocks, and runs them in a child shell with ARGUMENTS set from the trailing positional arguments. This subcommand replaces the legacy run_ff_command.sh helper. See flowforge run.
Internal command — invoked by the TUI controller when spawning new tmux windows. Hidden from flowforge --help; documented for completeness on the flowforge run page.
A handful of conventions hold across the entire surface; they are worth memorizing:
ARGUMENTS carries positional input. When a slash command is dispatched (either through Claude Code or flowforge run), trailing positional arguments are joined with single spaces and exported as ARGUMENTS to the child bash. Slash command bodies read it with ${ARGUMENTS:-}.
? and help are universal arguments. Most slash commands intercept ? or help as the first argument, print an in-terminal usage block, and exit 0. When in doubt about what a command does at runtime, append ? and read its own help.
DEBUG=1 enables tracing. Slash commands typically write [[ "${DEBUG:-0}" == "1" ]] && set -x, so prefixing any invocation with DEBUG=1 produces full bash tracing for diagnosis. The flag is opt-in and never on by default.
TMUX gates tmux-aware commands. The flowforge tui and flowforge worker subcommands refuse to start if TMUX is unset.
The binary’s exit code is the child’s exit code.flowforge run propagates the underlying bash exit code, so a slash command that exits 1 produces flowforge run ... exiting 1. Failures inside the binary itself (project root not found, path traversal attempt, missing command file) also exit non-zero with a descriptive error.
