flowforge init
FlowForge does not ship a flowforge init subcommand. Per ADR-0025 (Single-Install Architecture), bootstrap is a two-step flow against the global install, not a per-project initializer:
| Goal | Command |
|---|---|
| Install the asset bundle once per machine | flowforge install --global |
| Register a git repository with FlowForge | flowforge register-repo |
If you arrived here looking for a “create a new FlowForge project” command, the section you want is register a repository.
Why no init subcommand?
Section titled “Why no init subcommand?”Most CLI tools install themselves into a project directory: a package.json, a .tool-version, a generated config tree. FlowForge takes the opposite approach. The asset bundle (agents, slash commands, hook templates, scripts) lives in one place at ~/.flowforge/. Each registered repo gets a small per-repo state directory under ~/.flowforge/repos/<repo-id>/ for billing and session metadata.
The registered repository’s working tree is never modified. There is no .flowforge/ to commit, no scaffolding to manage, no configuration drift to chase across team members. Update FlowForge once with flowforge install --global and every registered repo gets the new agents, hooks, and commands at the next session. This is the Single-Install Architecture pattern.
flowforge install --global
Section titled “flowforge install --global”Materialises the FlowForge asset bundle at ~/.flowforge/. Run this once per machine.
flowforge install --globalThe --global flag is mandatory in v1.0 — it confirms intent and reserves room for future per-project install modes. The installer:
- Creates
~/.flowforge/if it does not already exist. - Extracts the embedded asset bundle into
agents/,commands/,hooks-templates/,scripts/,templates/,bin/,docs/, anddocumentation/. - Creates state directories:
repos/,logs/,cache/, and the sensitive.legacy-archives/(mode0o700). - Self-copies the running binary to
~/.flowforge/bin/flowforgeand creates aflowforge-hooksibling for the hook-shim contract. - Seeds
config.jsonandrepos/index.json(preserved on subsequent runs). - Prints a summary with installed counts.
Set FLOWFORGE_HOME to override the install path. The value must be an absolute path; relative paths are rejected so the install location does not depend on the caller’s working directory.
Re-running flowforge install --global is safe and is the standard upgrade path: asset directories are refreshed (so stale entries are pruned) while user state files survive untouched.
flowforge register-repo
Section titled “flowforge register-repo”Registers a git repository with FlowForge so per-repo state (sessions, billing events, hook integration metadata) has a home.
flowforge register-repo [path]With no positional argument, the current working directory is registered. With a path, the named directory is registered instead. Either way, the path must point to a git working tree.
| Flag | Purpose |
|---|---|
--id-salt <string> | Disambiguation salt appended to the hash input. Use after a collision is reported. |
--rebuild-on-startup | Auto-rebuild a corrupt index.json from per-repo meta.json files. Equivalent to setting FLOWFORGE_AUTO_REBUILD_REGISTRY=1. |
What it writes
Section titled “What it writes”~/.flowforge/repos/<repo-id>/— per-repo state directory.~/.flowforge/repos/<repo-id>/meta.json— canonical record of this registration.~/.flowforge/repos/index.json— updated to include the new entry.
The repo-id is a 12-character hash derived from the canonicalised remote origin URL. Repositories without a remote use the realpath of the working tree as the hash input.
What it does NOT write
Section titled “What it does NOT write”- Nothing inside the registered worktree. Your project tree is untouched.
- No
.flowforge/directory in the project. - No commits, no untracked files, no
.gitignoreedits.
The .git/hooks/ shim install is a separate concern (handled by ticket 1011-3) and is not performed by register-repo.
Examples
Section titled “Examples”Register the current directory:
cd /path/to/myrepoflowforge register-repoRegister a repository elsewhere:
flowforge register-repo /path/to/another-repoRegister after a hash-collision warning:
flowforge register-repo --id-salt prodRelated commands
Section titled “Related commands”flowforge tui— launches the controller after installation.flowforge run— execute any FlowForge slash command from the binary.flowforge version— print the embedded binary version./flowforge:session:start— first slash command to run inside a registered project.- Installation — end-to-end install walkthrough.
- First Session — the session ceremony that follows registration.