CLI reference

The CLI is one command, fibers, with verbs grouped below by lane. The same binary runs the hooks and the commands you type, so the reference is one list. The read verbs that list --json below print the served payload to stdout and any waiting inbox messages to stderr, so a script can parse one without the other. A verb without --json in its row renders text only, whatever flags you pass.

This page is transcribed from the CLI’s own help text (fibers --help) and a test fails if a command in that help text is missing here. It will become generated from the command table once that lands, so treat it as current but hand-kept.

Where the CLI looks

Thing	Order it is resolved
Deployment URL	CONVEX_CLOUD_URL in the environment, then ~/.fibers/deployment.json, then the built-in default
Credential	FIBERS_API_TOKEN in the environment, then ~/.fibers/credentials.json
Repo binding	.fibers.json at the repo root, written by fibers init

Sign in and bind

Command	What it does
fibers login [--force] [--deployment <url>]	Signs in through your browser and writes a personal credential for this machine. --force replaces a credential that is present but refused. --deployment points this machine at a deployment and seeds ~/.fibers/deployment.json; omit it for the default.
fibers init [--workspace <slug>]	Binds this repo to a workspace by writing .fibers.json, and fetches a workspace token. Without --workspace it lists your workspaces and asks, offering to create one.
fibers init --codex	Adds the fibers hooks to ~/.codex/hooks.json for OpenAI Codex CLI sessions, and writes the small script they call. Shows the change and asks first. Trust the hooks once with /hooks in Codex. See install the plugin.
fibers register	One-time machine token. The bootstrap path for a machine that cannot run the browser flow; needs the bootstrap secret in the environment.
fibers doctor [--json] [--marketplace <url>] [--launcher]	Verifies the whole chain, one line per check with its cure. Exit 0 when all is well, 1 when something is missing, 2 when something is waiting on you. See troubleshooting.
fibers mode [local|hosted] [--json]	Shows or sets whether this machine runs without an account (from 0.10.1). See local mode.
fibers features [--json]	Each module (work, messages, decisions, friction, areas): on or off, and which file decided it. Presence is always on. See features.
fibers features on <module> [--repo]	Turns a module on in ~/.fibers/config.json, or in this repo’s .fibers.json with --repo, which overrides the machine for that repo.
fibers features off <module> [--repo]	Turns it off. Its verbs leave --help and refuse with a one-line hint naming the file and the command to turn it back on.
fibers features off digest|update-notice	Mutes the session-start board digest, or the notice that a newer release is out, on this machine only. on restores it. See features.
fibers features on turn-labels	Puts this machine in the end-of-turn label trial. Off by default. While on, the Stop hook refuses a turn that ends without a fibers turn label, once per turn. off leaves the trial.
fibers features on lab	Turns on the Lab in the desktop app: fibers’ own trial views drawn on live data, each under the experiment that measures it. Off by default, and set per machine. The Experiments register itself needs no option.
fibers features on asides	Spools your own mid-turn messages on this machine (the mid-turn asides spike, ADR-0114). Off by default. While on, the UserPromptSubmit hook appends a message you typed while the agent was working to ~/.fibers/asides; nothing is sent. off stops it.

Hooks

Command

What it does

fibers hook <event>

Called by the plugin’s hook configuration, never by you. Reads the runtime’s hook JSON on stdin and emits at most one observation. Events: session-start, stop, notification, pre-compact, session-end, pre-tool-use, post-tool-use, post-tool-use-failure, stop-failure, subagent-start, subagent-stop. The two failure events record friction in the local store and send nothing. Always exits 0. See what is captured.

The work lane

Claims, progress and handover. These are the verbs an agent session runs while it works.

Command	What it does
fibers claim <ref> [--note "..."] [--triggered-by key@ISO@kind]	Claims a work item in this worktree and prints its brief, or says loudly that it has none. One active claim per worktree.
fibers log <kind> [--note "..."]	Records a progress event against the claim. Kinds: progress, blocked, unblocked, note.
fibers log blocked [--blocked-on <what>]	Marks the claim blocked. --blocked-on is human, agent or unknown; only human and unknown surface the session in the needs-you lane.
fibers release [--status done|paused|abandoned|failed] [--note "..."] [--hand-on <ref>]	Ends the claim. The note is the parting handover the next session reads. A done release is refused while the item has open children: --hand-on moves them under another item or direction first, or close or void each child.
fibers bump <ref> [--why "..."]	Records attention on a work item. Bumps decay over 14 days. A person’s bump and a session’s bump render differently.
fibers msg <ses_…|REF> "text"	Messages a session by id, or whoever holds a live claim on a ref. Refused when nobody does. Delivered with provenance at the recipient’s next hook touchpoint; it never wakes anything.
fibers pr refresh	Refreshes this branch’s open pull request into the mirror now. claim and log do this for you, throttled to once per five minutes.
fibers pr refresh --waiting	Refreshes every pull request an open pr-merged trigger in this workspace still waits on, so a squash-merged PR whose branch is gone gets mirrored and the trigger fires. Session start does this for you, at most once per ten minutes per machine; the verb reports what that silent pass does not.
fibers turn --outcome <label> [--blocks yes|no] [--note "..."]	Says how this turn ends, before the agent stops (the end-of-turn label trial). Labels that ask the owner: merge-ready, choose, go-ahead, manual-step, stuck; these need a one-line --note, and choose and manual-step need --blocks. Labels that ask nothing: stopping, still-working, waiting. An asking label puts the session in Needs you.
fibers turn stats [--json]	This machine’s trial cost, per day: stops refused for want of a label, and the time and tokens the extra step added. Read from a local log that is never sent.
fibers asides ls [--session <id>] [--json]	Your own mid-turn messages the UserPromptSubmit hook spooled on this machine, oldest first, with the claim the session held when each arrived. Off unless fibers features on asides. Read from ~/.fibers/asides; nothing here is sent anywhere.
fibers asides report [--json]	What the asides spike measured on this machine: hook fires by outcome, how often the queued message was on disk before the hook read it, and what the hook cost. Read from a local probe file that holds no text.
fibers asides classify [--session <id>] [--json]	Labels every unlabelled spooled message idea, correction or other, on this machine: the secret scan first, then one headless claude -p on the account that owns the session, one turn, no tools, 200 a day. The hook starts this for a session after each spooled row. Labels stay in ~/.fibers/asides/labels.jsonl; nothing is posted.

Reading the board

Command	What it does
fibers ls [--all] [--under <ref>] [--flat] [--json]	Live sessions and claims grouped by lane: needs you, active, blocked, idle. --all adds loose ends and recently ended sessions. --under scopes to one ref and the items linked part-of it. --flat is the ungrouped one-row-per-session shape. A clash line appears under any rows sharing a worktree, branch or ref.
fibers retire ls [--json]	Ended sessions and whether each can be retired: not running, claim closed, every PR merged (or, with no PRs, released done), worktree clean and pushed, transcript archived. Otherwise the first gate that held.
fibers events [--limit N] [--since today|<ISO>|<epoch-ms>] [--json]	Recent activity across sessions. The JSON is an envelope {events, truncated?, inbox?} when --since is passed or the checkout resolves to a local session; only the no-session, no---since path prints a bare array. Pass --since for a stable shape.
fibers find <words> [--everywhere | --workspace <slug>] [--all] [--json]	Finds a piece of work, or a session that never claimed one, by words from its titles, earlier titles, ref, branch, PR titles or notes, and says where it stands. Searches this repo’s workspace; --everywhere and --workspace ask you to confirm first. --all includes finished work. A search that finds nothing is kept on this machine for two weeks, in ~/.fibers/search-misses.jsonl.
fibers catchup [--workspace <slug> | --all] [--since looked|midnight|<ISO>|<epoch-ms>] [--md|--json] [--no-local]	The morning brief as facts: needs you, what moved since your last look, PRs waiting, loose ends on this machine, goals. Scoped to this repo’s workspace by default. --since looked (the default) is your caught-up mark, falling back to local midnight. --md renders; --json prints the facts object.

Work items and the work graph

Command	What it does
fibers work new|start "<title>" [--body "..."] [--note "..."] [--requires <ref>]... [--part-of <ref>]...	Mints a work item. start mints and claims it in one step. Edges are recorded at mint.
fibers work ls [--all] [--long] [--hot] [--owed] [--everywhere | --workspace <id>] [--json]	The backlog with derived status. --long adds scope lines, --hot keeps only bumped items, --owed keeps the items that wait on a person (@ marks one in any list), --everywhere merges every workspace.
fibers work show <ref> [--json]	One item in full: body, note history, children, what blocks it, and spec pointers resolved against this checkout (found, drifted or not found).
fibers work link <ref> [--requires <ref>]... [--part-of <ref>]... [--spec <path-or-url>]...	Records graph edges between existing items. A cycle is refused with the offending path named. --spec points at a committed spec file, recorded with the commit it was read at, or at an https URL.
fibers work unlink <ref> [--requires <ref>]... [--part-of <ref>]... [--spec <locator>]...	Retracts an edge or spec pointer recorded in error. Closed, never deleted.
fibers work move <ref> --to <ref> [--why "<text>"]	Re-homes an item under another item or direction in one write: its open part_of edges close and the new one is recorded. An item has one open parent, so a second --part-of is refused and points here.
fibers work note <ref> [--kind <kind>] "<text>"	Appends a block to the item’s body ledger. A finding by default; --kind brief writes the item’s brief.
fibers work revise <ref> --block <id> --based-on <revision> "<text>"	Revises a block. A stale --based-on lands as a suggestion rather than overwriting.
fibers work void <ref> --why "<text>"	Voids an item minted by mistake. Never deleted: the record keeps when, who and why, shows status voided, and drops out of work ls (--all shows it). Refused while a claim is open.
fibers work new "<title>" [--trigger <spec>]... [--for person|agent]	Mints an item gated by one or more triggers (pr-merged:#123, date:YYYY-MM-DD, asserted:<label>, manual). The item is not ready until every trigger has fired; fired is derived, never stored (ADR-0106). --for person sends the fired item to needs-you.
fibers work trigger add <ref> <spec> [--for person|agent]	Adds a trigger to an existing item.
fibers work trigger retract <ref> <trg_id>	Retracts a trigger added in error. Closed, never deleted.
fibers work assert <ref> <trg_id> --why "<text>"	Records that an asserted:<label> trigger’s condition is now true; the item becomes ready once its other triggers have fired.
fibers work owe <ref> --to person|agent|none	Records whose action the item waits for: a person’s or an agent’s. An audience, not an assignee; it decides where the item surfaces (work ls --owed, needs-you, Loose ends). none clears it. work new --for person records it at mint.
fibers work done <ref> [--why "<text>"] [--hand-on <ref>]	Records that a person finished the item by hand, for items no session ever claimed. Status shows done; the item stays on the board as finished work. Refused while the item has open children: --hand-on moves them under another item first, or close or void each child.
fibers work conclude <ref> --result positive|negative|inconclusive --note "<text>"	Writes the conclusion block with its result, releases this session’s claim and finishes the item. Refuses if the item has no hypothesis.
fibers work goal [<ref>] [--clear]	The standing goal. With no ref, prints it with its roll-up and the next open child. With a ref, marks that item as the goal (the newest open mark is the goal). --clear unmarks it. Session start prints the same line; a claim outside the goal gets one note.
fibers work direction [<ref>] [--clear]	Directions, the layer above work. With no ref, lists the live ones with their roll-up. With a ref, marks that item as a direction (many per workspace). --clear unmarks it. Where a live direction exists, work new or work start with no --part-of, --for person or --loose is refused and lists them ranked against the title; --loose mints with no direction on purpose and counts as scatter. A claim on an item under no live direction gets one note.

Decisions

Command	What it does
fibers decide "<title>" [--body "..." | --body-file <path>] [--anchor <type>:<ref>]... [--supersedes D-<n>]	Records a decision and anchors it to the active claim. Write the body as markdown in a file; a one-word title or a body line over 1,000 characters is refused.
fibers decisions [ls|--all]	Lists decisions, status first. Status is derived, never set by hand.
fibers decisions show D-<n> [--history]	Serves one decision. A superseded decision serves its successor by default.
fibers decisions qualify D-<n> --kind qualifier|rebuttal|extension --note "..." [--cause <ref>]	Attaches a qualification without rewriting the record.
fibers decisions void D-<n> --why "<text>"	Marks a decision recorded in error. It is never deleted, and drops out of lists.
fibers decisions search "<query>"	Semantic recall through the engine, served status first.
fibers decisions export [--out <dir>] [--format md] [--repo <host/owner/name>]... [--allow-empty] [--prune]	Writes this repo’s decisions as markdown, one file each plus an index, into docs/decisions/ by default. Deterministic and read-only against the service.
fibers sync	Drains the local outbox to the recall engine.
fibers numbers add <NAME> --width <w> --after <n>	Configures a numbering namespace for the workspace, such as ADR. Member only. --after is the highest number already in use.
fibers mint <NAME> "<title>"	Prints the next number in the namespace and its file-name slug. Offline, prints a guess from the last counter seen, marked provisional.
fibers mint ls <NAME> [--limit <n>] [--json]	Lists the namespace’s numbers, newest first, with the claim that holds each and any guesses not yet confirmed.
fibers mint confirm <NAME>-<number> --title "<title>"	Confirms a number held offline. If another branch took it, says which number the record became.

Friction

Recurring friction is counted on this machine from the local store. Only hashes and refs ever leave it.

Command	What it does
fibers friction ls [--since Nd|Nh|today|<ISO>] [--by day|session|agent|repo] [--repo <name>] [--all] [--offline] [--json]	Signatures seen three or more times across two or more sessions, with count, sessions, days, agents, corrections and trend. --all adds the rest.
fibers friction show <sig-prefix> [--offline] [--json]	One signature: template, per-day counts, sessions, agent types and the last few local excerpts. Both fetch any recorded fixes; --offline skips that lookup.
fibers friction fix <sig-prefix> --by <#N | owner/name#N | PR URL | ref> [--undo]	Records, or withdraws, that a PR or work item fixes a signature.
fibers friction next [--since ...] [--repo <name>] [--json]	The one signature a fix loop should act on next: top ranked, not skipped, unfixed or seen again since its fix.
fibers friction skip <sig-prefix> --why "<reason>" [--undo]	Deny-lists a signature no code change fixes. fibers friction skip --parent <ref> sets the standing parent item the loop mints under.
fibers friction slugs [--json]	This project’s authored friction kinds, a closed list, with 7-day and 30-day counts.
fibers friction note <slug> [--new "<description>"] [--about <sig-prefix>] [--pointer <id>] [--text "<note>"]	Records one correction against a slug. An unknown slug is refused with the closest ones listed, unless --new adds it.

Areas

Which parts of a repo its pull requests and sessions touch, worked out on this machine. Off until you run fibers features on areas. Only folders git tracks become areas. What is sent: PR numbers, area slugs (short hashes), roles, each label’s confidence (the share of the PR’s or session’s files behind it), whether that file list was complete, and each area’s name: its package name, or its folder’s name when it has no manifest, and the repo’s name for the repo root. The service works out the counts from those. No file path, branch or PR title leaves the machine. With the module on, each session also records, at the end of every turn, the files changed in its worktree since it started. Once the branch has merged in the default branch, those are measured from where the branch meets it, so the default branch’s own changes are not counted as the session’s. A file stays on the session’s list once it has been touched, even after the work lands on the default branch or is undone. That list stays in ~/.fibers/session-paths/ on this machine and is never sent; only the session’s labels are. The lists are kept until you delete them. A work item’s areas are not stored: the service works them out from its pull requests and its sessions each time you ask.

Command	What it does
fibers areas backfill [--limit <n=200>] [--dry-run] [--force] [--json]	Reads this repo’s most recently updated pull requests (200 unless --limit says otherwise) and the files each touched through gh, labels each PR with its roles and areas, and posts the areas and labels. Prints a line per page of PRs fetched and per 50 posted, then areas <n> · prs <n> · labels <n> · truncated <n> · sessions <n>. It then re-posts the labels of every session file kept on this machine for this repo, worked out again from the stored file list against the areas of the worktree the session ran in, or this checkout’s when that worktree is gone. A session whose labels are already posted as they stand is not sent again unless --force is given, which re-posts every one so a set changed on the service can be put back; the file lists themselves are never sent. --dry-run classifies, counts the sessions and posts nothing. --json prints the five counts.
fibers areas ls [--json]	This repo’s areas with their roles, label count, PR count and session count, most PRs first. A PR whose file list was cut short counts as partial. --json prints the served payload.
fibers areas show <ref> [--json]	The areas and roles of one work item, with how many of its pull requests and sessions carry each, areas first. The item’s pull requests are the ones fibers work lists for it. Prints no areas yet when nothing is labelled, and no work item <ref> in this workspace for an unknown ref. A ref typed in lower case is read in upper case, as fibers work show reads it. --json prints the served payload.

Loose ends

Command	What it does
fibers checkin tick	One pass of the on-device runner behind the desktop app’s Loose ends screen. It acts on the rulings you recorded in the desktop app once their take-back window has passed, then, every 15 minutes and at 07:00, finds sessions on this machine, checks them and writes cards under ~/.fibers/checkin.
fibers checkin shadow-report [--json]	How often Jev’s label agreed with Claude’s answer on the sessions the runner checked, by Jev confidence band and by direction, and against your own rulings. Shadow mode logs beside every check once a Jev key is in ~/.fibers/jev.json; it changes no card. --json prints the stats object.
fibers checkin autoprogress [status] and fibers checkin autoprogress on [--yes] | off | set <line> [--item <ref>]	Auto-progress on this Mac: whether it is on and why not, the finish lines and the limits. on shows every message it can send into an idle session; on --yes records that you accepted that text and turns it on. set picks the default finish line (off, done-locally, pr-opened, ready-to-merge, merged, merged-and-archived) or one work item’s. Nothing is sent until you press Nudge on the Sessions board.
fibers checkin closeout-brief --instance <name>	Prints the close-out brief for one desktop instance: the prompt its daily scheduled task runs to map, rescue and archive the sessions you ruled No or Drop on.
fibers checkin closeout-pending --instance <name> [--json]	The sessions that instance’s close-out still has to do: queued, with no done or cancel record, and still ruled No or Drop. A reopen or a newer ruling takes a session off the list. --json prints a JSON array.
fibers checkin closeout-done --instance <name> --card <cardId> --ruling-at <ms> --result archived|held|skipped [--reason "<text>"]	Records what the close-out did with one session, as one append to the queue. The runner puts it on the card: archived, or held with the reason.

Desktop and maintenance

Command	What it does
fibers desktop ls	Desktop instances on this machine and which are running.
fibers desktop resume <sessionId|REF> [--instance <name>]	Raises a session in the instance that owns it. A work ref opens the session holding its newest claim on this machine. --instance names one outright.
fibers desktop new "<prompt>" --instance <name> [--folder <path>]	Prepares a new session with the prompt prefilled. You press Enter; it does not run on its own.
fibers open <sessionId>	Deprecated alias for fibers desktop resume.
fibers update	Brings this machine up to date. Asks Claude Code to refresh the marketplace and update the plugin, then prints the old and new versions. On a developer machine it first fast-forwards the source checkout (only when it is on main with no changes), re-promotes the launcher, and rebuilds a plugin installed from a local folder.
fibers promote [--from <checkout>]	Copies the CLI at HEAD into ~/.fibers/releases/<sha>/ and points the launcher at it, so what runs stops changing when a checkout does. Refuses a dirty or non-main tree. --list shows promoted releases; --release <sha> rolls back without rebuilding.

Exit codes

Every verb exits 0 on success. Exit 1 is a usage mistake, printed as what was wrong, or an operational failure such as the service refusing the call. A flag that needs a value and gets none, or gets another flag, is refused rather than recorded as empty: a corrupted note is indistinguishable from a real one later, and an unrecorded note you are told about is better. Write --flag=value for a value that begins with --, and put free text after a bare --. Hook invocations always exit 0 so the runtime is never blocked. Two verbs use exit 2 for “waiting, not failed”: fibers doctor (0 all ok, 1 something missing or a launcher problem, 2 waiting on you) and fibers friction next (2 when fix state is unavailable or another sweep holds the lease). A verb whose module is off exits 1 with that hint.