On your machine

The forge holds the truth; forge keeps a copy of the parts you work on, the way a music player keeps the albums you listen to — downloaded, fresh, and yours when the network is not.

forge login forge.example.com    # a URL and a token, stored 0600 (macOS: keychain)
forge sync                       # clone what is missing, fetch the rest, report
forge status                     # the same report, without touching the network
forge                            # the local UI over your clones

A bare host means https; localhost, 127.0.0.1 and [::1] mean http. Plain http:// to any other machine is refused — the token would cross the network in clear — unless you log in with --insecure for a host you trust; that is kept with that workbench only, and FORGE_URL to another such address is refused too.

Repos land under ~/src/<host>/<owner>/<name> — the path is the identity, so two forges with a docs repo never collide, and the filesystem is the index (there is no local database of "your repos"; the walk finds them). --root or FORGE_ROOT moves the library; FORGE_URL and FORGE_TOKEN override the stored config for a script or a CI job.

forge sync --watch --interval 5m   # notify only when something CHANGED
forge sync --ff                    # fast-forward clean repos, and only those
forge pin owner/name               # ask the workbench to keep this one here
forge ls                           # what is here, and how stale
forge open owner/name --web        # the page, in a browser
forge ship 12                      # land pull #12 after a y/N, as Merge does
forge pulls                        # open pulls of this clone, newest first
forge runs                         # the crew's last 10 runs here: state, agent, #N, title, age, cost
forge data notes "select * from users" --json   # read an app's SQLite, read-only, secrets masked
forge asks                         # what waits on you, most important first
forge asks --repo owner/name       # only that repository's; --json for the API's answer
forge asks --ship 1 3              # decide by the line numbers just printed: planned, then Apply? [y/N]
forge asks --close 2 --reason "words"   # also --dismiss 4; --yes skips the question (needed without a TTY)
forge asks --undo <id>             # take back a decision by the receipt id it printed
forge tell "make the header smaller"   # tell the crew, about this folder's repo (--repo owner/name overrides)
forge map                          # the plan of this clone: working, ready, waiting
forge search retry budget          # code, issues, pulls and repos you can read; exits 6 on "not now"
forge search x --kind pulls --limit 5   # one kind, five hits; --json marks truncated.issues when more matched

forge tell makes an issue of your words (1 to 2000 characters) and prints its address. --variants 1-4 asks for that many attempts and --from /path names the workbench page you were looking at, as the API takes them. Words that start with a dash go after --: forge tell -- "--fast".

The MCP tell tool takes from but not variants. The terminal (tty) takes neither.

forge ship <number> reads the repository from --repo owner/name or from the folder's origin when it points at your workbench, shows the pull's title, check and whether it merges, and asks Ship #12? [y/N]. --yes skips the question; with no terminal and no --yes it refuses (exit 2). The merge's rules stay the forge's: a refusal prints the forge's words and exits 5 (3 for a refused token), and is never retried.

forge pulls prints one line per pull: #N, the title cut to the terminal width, the author, the check (green, red, running or none) and the preview address when the repository is an app. It asks about the repository your origin remote names, when that remote is on the configured workbench; anywhere else it exits 2 and says so, and --repo owner/name names one yourself. --closed lists closed pulls, --json prints the API's answer, and a list longer than the 100-pull pages it follows is marked as cut. This is a shell command on purpose: the terminal UI of the forge (ssh, src/tty.ts) already has its own pulls screen, and the local UI is about working trees, not the workbench's conversation; the pulls API and MCP are the other doors.

forge map reads the plan of the same repository (--repo or origin, as for pulls) from GET /api/v1/repos/:owner/:name/map and prints three groups, each headed with its count: Working (#N title — assignee), Ready — the map's startable subset of its ready issues, unassigned and not held, so its count matches the map page's ready count (#N title — pillar) — and Waiting (#N title — waits on #A, #B, open blockers only). Titles are cut to the terminal, and a group past 15 lines ends … N more. --json prints the API's answer unchanged; an unknown repository prints the forge's words and exits 1 (3 for a refused token, 5 for a forbidden one). The same plan is a screen in the forge's terminal UI: press m on a repository's issues list (src/tui/screens/plan.ts).

sync never merges, rebases, resets or checks anything out. --ff is the one exception and it fast-forwards a repo only when the tree is clean, nothing is ahead, no rebase or merge is half-finished, and merge-base --is-ancestor has proved that moving the branch cannot lose a commit. A dirty repo is reported and left exactly as you left it.

sync hands git your token only for a remote on the workbench's own origin (scheme, host and port) over https, or plain http to loopback. A clone whose origin was edited to anywhere else is fetched without the token, and its row says no token sent.

forge with no arguments opens the local UI on the same runtime as the SSH one: the library of clones, then a lazygit-shaped working-tree screen — space stages, enter opens the hunks, s stages one, c commits, P pushes, b branches, l log, z stashes, ? shows every binding.

forge runs lists the last 10 runs of the same repository (--repo owner/name names another, --json prints the API's answer). Each row of GET /api/v1/repos/:owner/:name/runs carries agent (the agent run's username, null for a check or deploy), number and title (its pull or issue, null for none), so no client reads them out of a branch name. The SSH terminal's door is H on a repository: the runs screen (src/tui/screens/runs.ts), read through the same listRepoRuns, so a guest sees only what the page shows them and a stranger sees no cost or session.

In the SSH terminal, enter on a run opens its log (the last 200 lines, following new ones while it runs; "Not found" where the web would say so), and o there prints the web address (src/tui/screens/runlog.ts).

Build it once and put it on your PATH:

bun build --compile src/cli/main.ts --outfile dist/forge

That produces a self-contained binary (it embeds the Bun runtime, so expect something in the 60–110 MB range; dist/ is gitignored and binaries are never committed). Until you build it, bun run src/cli/main.ts … is the same program.

A whole pack, one command

git clone <forge>/trevato/forge.git && cd forge && bun install
bun scripts/pack.ts up games      # or: business

It boots a forge on http://localhost:3000 with its state in forge-data/, deploys the pack's apps with their full history and a follow on their source, sets up the crew, and asks for nothing. Only the model credential is yours to add (ANTHROPIC_API_KEY in the environment, or Settings › Subscriptions); until then the crew is off and the command says so. No data, secret or variable is carried from the source. See docs/features/packs.md.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs