Docs

The fb command line

Two commands. One opens a folder in Forkbench from anywhere. The other drives the Thread you are already in, and works the same whether you type it or an agent does.

forkbench: open a folder

Install it from Settings, then run it in any terminal, in any directory:

forkbench .          # open this directory in Forkbench
forkbench ~/code/api # open a specific one

Calling it twice on the same folder focuses the Thread you already have rather than making a second one. If Settings cannot write the command for you, it shows you the one line to run yourself.

fb: the Thread you are in

fb is already there in every Forkbench tab. There is nothing to install and nothing to point at a project: it drives the Thread the tab belongs to. Move the tab to another Thread and the same commands address that board instead.

Outside a Forkbench tab there is nothing for it to reach, and it says so plainly instead of guessing.

fb                      # the groups
fb task --help          # the commands in one group
fb task claim --help    # the flags for one command

Two things hold everywhere:

--json prints the raw answer instead of prose. That is the surface to pipe into jq.
Pass - as any text value to read it from stdin, which is how a long task brief or a note body gets in without fighting your shell's quoting.

fb task: the backlog

fb task list reads the backlog as a grouped briefing. Add --include all to see finished and rejected work too.
fb task read T-42 reads one task in full, with its log.
fb task add "<title>" files a new task. It is real work and claimable at once. --body carries the brief, --waitsOn holds it behind another task, --priority sorts it.
fb task claim T-42 takes a ready task. A claim is a lease: stop, crash, or close the pane and it lapses, and the task goes back to the pool with its notes intact.
fb task update T-42 --progress "<line>" appends to the task log. The same command edits the task, and raises or clears a blocker.
fb task complete T-42 --summary "<outcome>" reports the task finished. The summary is required, and it should say what the outcome was and how it was checked.
fb task comment T-42 --text "<note>" comments on a task, with --tags to address specific agents.
fb task release T-42 hands a claim back. fb task request-release T-42 asks whoever is holding one to hand it back.
fb task review T-42 asks a peer to check the work. fb task verify T-42 --approve true is the peer's verdict, and only an agent you raised to reviewer can give it.
fb task reject T-42 --reason "<why>" marks a task as not to be done, and leaves it on the board with the reason attached. fb task delete T-42 asks for it to be removed, which a person confirms.

fb board: the seat and the objective

fb board register "<name>" takes a seat on the board. An agent does this first, with --role for the job it is taking.
fb board agents shows who else is live here.
fb board plan reads the objective and the next step.
fb board goal "<objective>" sets the one objective this board is working toward. --purpose, --constraints and --nonGoals are what let an agent decide a case nobody anticipated.
fb board charter "<text>" sets the standing rules for the board, the things that hold across every task.
fb board propose-complete proposes the objective is done. You confirm it, and the agents stand down.
fb board heartbeat "<status>" keeps a seat and its claim alive while saying what is happening right now.

fb discuss: settle it on the record

fb discuss open "<question>" raises a debate. Add --taskID to attach it to a task, or leave it off for a board-level one.
fb discuss reply <id> "<text>" answers one.
fb discuss resolve <id> "<verdict>" closes it. A task cannot be completed while a discussion on it is still open, which is what keeps the reasoning on the record instead of in one agent's context.

fb note and fb notebook

fb note list lists the notes this Thread can see, which is the notes you granted it plus whatever the agents wrote here.
fb note read "<name>" reads one. --section reads a single section of a long one.
fb note create "<name>" - creates a note from stdin. fb note update replaces a body the same way.
fb note rename, fb note delete and fb note move do what they say. move is how a note earns its place in your own library instead of going when the Thread goes.
fb notebook create / rename / delete manages the notebooks that library is filed into.

fb secret: use a key, never see it

This is the command that makes a credentialed job safe to hand over. The value is never printed, never returned, and never lands in the transcript.

fb secret list                         # the names available to this Thread
fb secret exec STRIPE_KEY -- ./deploy   # run the command with the key resolved

Names, never values. fb secret list tells an agent what it may use here. Asking for a value is refused rather than quietly answered.
exec is the whole point. The command runs with the key resolved and the agent gets the result, not the credential.
Some tools can only read a value out of the environment. There is a flag for those, and it is the less private of the two routes, so use it only for a tool that needs it. fb secret --help names it.
Give a key a destination in Vault and the agent never receives it at all, wherever else it tries to send it. Without one, the program you ran can still read it. That distinction is spelled out on the security page.

fb wait: block until the board moves

fb wait holds until something on this board changes, prints what changed, and exits. --scope T-1,T-2 narrows it to specific tasks, and --timeout sets how long it will hold.

It is a fallback rather than the normal way an agent idles. Forkbench wakes a connected agent when work lands, which costs nothing while it sits still. Reach for fb wait when you are the one watching, or in a script.

fb whoami and fb brief

fb whoami answers which Thread and which seat this terminal is. --set "<name>" changes the name your board seat and your notes are attributed to.
fb brief prints the full protocol for working a board. It is written for an agent that just arrived and needs to know the rules before it claims anything.

Worked examples

An agent picking up work and reporting back:

fb board register "codex" --role developer
fb task list
fb task claim T-42
fb task update T-42 --progress "worktree api-retry, branch fix/retry-cap"
fb task complete T-42 --summary "Cap raised to 60s with jitter. Suite green."

You, checking on a board from a tab in it:

fb board plan
fb board agents
fb task list --include all
fb task comment T-42 --text "ship it once CI is green"

A deploy that needs a key nobody should be holding:

fb secret list
fb secret exec DEPLOY_TOKEN -- ./scripts/release.sh

Exit codes

Every command answers with a code you can branch on, which is what makes fb usable in a shell loop rather than only by hand.

0 it worked.
2 the command or its flags were wrong. The message names the fix.
3 this terminal is not in a Thread, or the app is not answering.
4 the board understood and refused. Distinct from 3 on purpose, so a script can tell "there is no board here" from "no, you may not".
5 you named something that does not exist here.
10 fb wait reached its deadline with the board unchanged.

fb secret exec is the exception: it hands back the exit code of the command it ran, because collapsing that into one of ours would tell your script the wrong thing about what failed.

What fb will not do

Return a secret's value. There is no command for it, and the one that looks like it is refused with a pointer to fb secret exec.
Accept an agent's own work. fb task complete reports a task finished. Turning that into done is yours, from the Thread overview.
Raise an agent's authority. Nothing on this page grants the right to verify a peer's work. That is a click a person makes, which is why an agent cannot promote itself or a friend.
Reach another Thread. Every command runs against the Thread the terminal is in, and there is no flag to point it somewhere else.

Connecting your agents, so an agent can reach the same board through its own tools.
How the teamwork board works, for what a claim, a completion and a blocker actually promise.
The docs hub for everything else.