Fir CLI

fir is the command line for Fir, on Linux, macOS and Windows. Its commands are shaped like the git and pull request commands you already know, so fir status, fir diff, fir log, fir branch and fir pr create do what their names say. fir --help lists the commands, and fir <command> --help lists a command’s flags.

How fir behaves

• No prompts. A command never stops to ask a question, so it runs the same in a terminal, a script, CI and an agent’s sandbox.
• One contract with frazer. Piped output is TSV with a header, --json and --format=ndjson are there on request, every error is one JSON envelope on stderr with next, and exit 13 means a person must act. The CLI for agents has the whole contract.
• JSON everywhere. Add --json for output a program reads. Field names use the same words as these docs: pull_request, version, branch, merge_queue, and change_id for a pull request’s stable internal key.
• Plan first. Every command that changes something takes --dry-run and prints what it would do.
• Where an answer is true. Commands that read code name the position they answered: a commit (main@48213), a pull request version (#482 v3) or a workspace with its unsaved edits (ws/s-81f2).
• Server-side. Merges, rebases of a stack and the merge queue run on the server. Your machine never merges and pushes.

Positions you can name: a commit ID, main or another branch, a sequence number such as main@48213, main@verified, a pull request and version such as #482 or #482 v3, and a workspace such as ws/s-81f2.

Your workspace and files

Command	What it does
fir status	The workspace you are in, its branch and its base, such as ws/s-81f2 · lena/retry-errors · base main@48213
fir diff	What changed in the workspace. fir diff <a> <b> compares any two positions
fir show <at>:<path>[:<lines>]	A file or a range of lines at a position, with line numbers
fir log	Commit history. --symbol follows a symbol across renames and moves; --search finds commits; --plan 469 lists a plan’s commits
fir blame <path>	Who changed each line. --provenance adds the person or agent, the session and the pull request
fir snapshot	Snapshot the workspace now. Frazer sessions snapshot every write on their own
fir watch	Snapshot on every file change, in the foreground
fir commit	Make a commit from the workspace
fir ws	Workspaces. fir worktree is another name for the same command
fir sync	Move the workspace onto a newer base
fir clone <owner>/<repository>	Get a repository onto your machine

Branches

Command	What it does
fir branch	List, create and delete branches. Protected branches, such as main, change only through merges

Pull requests

Command	What it does
fir pr create	Open a pull request from your workspace. --fixes 479 links an issue; --repo opens it on a repository you cannot write to, from a fork made for you
fir pr list	List pull requests. --view now, needs-you, by-node (by-plan stays an alias), outcomes, all, needs-others or flow; --query in the one query language; --json returns counts, stages, exception groups, groups and rows; --turn @me lists the ones waiting for you
fir work	My work: what needs you from every source, your agents, your plans and what changed; --all-projects, --json
fir pr view 482	A pull request: its intent, versions, checks, reviews and merge state
fir pr checkout 482	Work on a pull request in your workspace
fir pr diff 482	Its changes. --from 2 --to 3 compares two versions; --since-my-review; --mode structural
fir pr edit 482	Change its details
fir pr push	Add a new version to the pull request your workspace belongs to
fir pr ready 482	Mark a draft ready for review. Agent pull requests start as drafts until their checks pass
fir pr review 482, fir pr comment 482	Submit your own review, and comment
fir pr checks 482	Its checks. --failed shows the failing excerpt first
fir pr tests 482	New failures, flaky tests and tests fixed by this pull request
fir pr blockers 482	Exactly what still blocks the merge: each rule, what it needs and what it has, the queue position and test batch
fir pr why 482	The merge receipt of a merged layer, or the one condition an open layer still waits for
fir pr second-opinion 482	Ask Frazer Reviewer for the second opinion auto-merge reads; --wait; exits 0 pass, 11 fail, 13 a person must unblock, 7 no verdict yet
fir pr preview 482, fir pr test 482, fir pr affected 482	A preview of the pull request on frazer.run; its test plan and verdicts by depth; what it affects across repositories
fir pr merge 482	Merge. --auto merges when the rules allow it; --expect-version 3 fails if a newer version exists
fir pr suggestions apply 482 --all	Apply suggested edits as one new version
fir pr reviewers suggest 482	Reviewers suggested by ownership, history and load
fir pr revert 482	Open a pull request that reverts a merged one
fir pr update 482 --plan-version latest	Move the pull request’s plan link to the plan’s newest version
fir pr close 482, fir pr reopen 482	Close and reopen
fir merge	Merge the pull request of the workspace you are in
fir pr checks 482	The checks at the pull request’s version; exits 0 when every check passed, 11 when one failed, 7 while one still runs
fir pr request-review 482 --reason "…"	Stop this pull request’s auto-merge until an owner reviews it
fir pr why 482 --attestation	The merge receipt as an in-toto Statement in a DSSE envelope, for any verifier

Stacks and the merge queue

A stack is named by its name, its ID or any layer’s number (Stacks and conflicts).

Command	What it does
fir stack create --plan 469	A new stack with a planned layer per plan item; --plan new --from-issue 479 opens the plan’s pull request as layer 1
fir stack submit	Create or extend a stack of pull requests from your workspace; --split-by plan, paths or commits
fir stack add --ws	A new layer on top, with a workspace on the layer below’s head
fir stack view, fir stack list	The map, states and blockers; your stacks with --mine
fir stack insert, split, fold, move, reorder, drop, detach, absorb, link, unlink	Typed edits, each with --dry-run and --expect-version
fir stack log	Stack versions with the operation and actor of each
fir stack restack	Rebase the stack onto the newest base now
fir stack plan-sync	Move the stack’s open layers to the plan’s newest version
fir stack merge --up-to 483	Merge the stack up to #483 as one entry in the merge queue; --all, --together, --auto
fir stack revert	Revert a merged layer with the merged layers that depend on it; --from 484
fir stack follow 494	Build on another stack’s layer, as an outside dependency
fir stack up, down, top, bottom	Move your workspace to another layer’s workspace
fir stack close, fir stack reopen	Close or reopen a stack, undoably
fir stack preview <stack>	A preview of the stack’s top, updated in place on every push
fir node review <node>	Review one plan level (a phase by default) with its stacks, as one decision
fir queue status main	The merge queue of a branch: partitions, test batches, depth and the forecast
fir queue list, partitions, entry, batches, bisect, forecast, insights	Entries by any grouping; partitions; one entry’s place; test batches and their bisections; the forecast; the measures
fir queue pause, resume, drain, freeze, thaw	The queue’s controls, each with a scope, --reason, --until and --plan first; --admit hotfix for a freeze
fir queue priority, fir queue limits set	An entry’s priority with a reason; a requester group’s capacity share in a partition
fir queue remove	Take a pull request out of the queue
fir auto-merge status	The control strip: what is paused, frozen or throttled over your scope
fir auto-merge policy view, plan, apply	The auto-merge policy; a change planned, then applied; fir auto-merge audit shows its decisions
fir auto-merge pause, resume, throttle, freeze	Controls by intent at any scope (a plan level, a campaign, an agent, a repository), with --reason; agents may pause, never resume
fir auto-merge explain	The policy in force in plain words: what merges with no person, what needs one, who checks, how to stop it
fir auto-merge audit plan, audit next	The audit sample per class with its bound; the next items to audit
fir queue priority <entry> hotfix --case <case> --evidence <ref>	An agent’s own fix at hotfix: culprit_revert, incident_fix or verified_red_fix, at most 5 an hour per repository
fir queue hotfixes	Every hotfix entry with its case and outcome, --by agent or person

Conflicts

Command	What it does
fir overlaps	Every open overlap of your workspace, pull request or stack, with its kind, the hunks and a suggested action
fir conflicts 535	A conflicted layer’s base, sides, hunks, intents and the resolvers tried so far
fir resolve 535	Resolve a conflicted layer as its next version; --tool structured or --tool model
fir hot --by conflicts	Files many open layers change, with their proposed remedies (fir hotpaths stays an alias)
fir conflicts map	Conflicts by repository, partition, file and resolver; --org, --window 24h

History, undo and moving changes

Command	What it does
fir activity	The activity log of your workspace, a pull request or a branch
fir undo <operation>	Undo an operation, with a plan of what it changes. An undo can itself be undone
fir restore <operation>	Bring back the state an operation left
fir split, fir absorb	Split a change in two; fold edits into the commits they belong to
fir backport 482 --to release/2026.10	Bring a merged pull request to a release branch
fir fork	Make a fork in your own namespace
fir bisect	Find the commit that broke something, across main@N

Ask the codebase

Command	What it answers
fir search	Literal, regex, path and symbol search, at any position or in your workspace
fir symbols <path or directory>	The definitions in a file or directory, with their line ranges
fir def <name>, fir def <path:line:column>	Where something is defined
fir refs <symbol or path:line:column>	Every reference, grouped by file
fir calls <symbol> --callers	Who calls it, or what it calls with --callees; --depth 2
fir impls, fir hierarchy	Implementations and type hierarchy (fir types stays an alias)
fir map --budget 2000	A ranked map of files and symbols that fits a token budget
fir context	The session context for a session, a pull request or a plan (--session, --pr, --plan), by part (--part 1), with reasons (--explain)
fir why <path:line, symbol, #PR or commit>	Why it exists: the change that wrote it, its plan, the requirements, the decisions in force then and now, the session and what came after; --as-of main@48190, --concise
fir origin <path:lines>	The origins of a range of lines, with moves and the changes skipped as format-only, moves or reverts
fir tests <symbol or path>	Tests that exercise it, with their last results; --covers <test> the reverse
fir failures --since 7d	Recent failing checks and tests on these paths
fir trace explain	Map a stack trace to the code
fir hot	Paths that change and break most
fir graph query	Bounded, read-only queries over the code graph
fir deps list, fir deps why, fir deps graph	Dependencies, why one is there, and what uses what
fir deps update <package>	Update a dependency in your workspace

Plans and records

Plans, specs, decisions, milestones and every other record of a plan repository. A record is named by its number (469, acme/plans#50), its key (ADR-0031) or its path.

Command	What it does
fir record new <type>	Create a record from its type’s template and open its pull request; --title sets the title; --home plans or --home repository chooses where it is stored
fir record view <record>	A record, now or --version 2; --json returns the parsed blocks, links and states
fir record list	Records by --type, --path, state, owner, milestone or link
fir record diff <record> <v> <v>	The structured diff between two versions, by section and row ID
fir record links <record>	Its links in both directions
fir record history <record>	Every version of a record, across moves between homes
fir record move <record> --to plans	Move a record between homes in one reviewed pull request; --to repository
fir record move --repository <repository> --to plans	Move every record of a repository; --dry-run first (fir records stays an alias)
fir record settings --repo <repository>	The layered records setting: mount, extra record roots, locks
fir links coverage --repo <repository>	Merged pull requests, commits and lines accounted for by links; --since 30d
fir record check <path>	The type’s rules and the record checks; --fix applies safe fixes; --baseline; exits non-zero only on an error
fir record types	The types in scope; --show risk prints one type’s definition
fir record rules	The lint rules a type applies (--type), a rule’s source (--explain), its tests (--test), a backtest (--backtest)
fir spec view, fir decision view, fir milestone view	fir record view for that type
fir trace <spec>	The traceability matrix; --baseline storefront-2026.11; --format reqif
fir impact <requirement>	What a change to a requirement, criterion, decision or contract touches
fir record evidence	Change evidence for an audit: --framework soc2 --period 2026-Q3
fir lsp	A language server (LSP 3.17) with the record checks, for any editor

Record types and packs

Command	What it does
fir type list, fir type view <type>	The types in force for a scope; one type’s definition, card or generation schema (show stays an alias)
fir type levels list, view, align, test	Level schemes: list them, read one, align a scheme’s levels to the ladder’s rungs, test a change
fir type explain <file>	A type definition explained line by line
fir type test <type>	Validate, compile, cost, classify the change and backtest over existing records
fir type add --from <file>	Add a type from a YAML file: the checks above, then its pull request
fir type adopt <type>	Find docs that look like the type and draft the plan that adopts them
fir type resolve <type>	Which layer supplies each field, section and rule of a type
fir pack list, fir pack add <pack>, fir pack upgrade <pack>	Packs in scope; install one with a lock entry; upgrade one through a plan

Programs

Command	What it does
fir program view <program>	A program’s tree with rollups; --depth 3, --lens squad
fir program ready --squad <squad>	Approved, unblocked, unclaimed items a squad may take now (fir ready stays an alias)
fir program map, readout, next, waiting, prs, changes, insights, levels, baseline	The Map as data; the readout; Do next; waiting on people; the pull requests by node; changes; insights; the levels; the baseline the plan line reads
fir node move <node>	Move a node and its subtree; --to-squad hands it to another squad
fir node log <node>	Every version of a node’s text and every move, across files and records
fir program list, fir program where <ref>	Every program you can read; where a plan sits in its programs

Plans

Command	What it does
fir plan new --from-issue 479 --tier task	Draft a plan from an issue in docs/plans/ and open its pull request; the number comes at its merge
fir plan use 469	Make it the workspace’s active plan: every pull request from here links it
fir plan view 469	The plan; --at main@48190 as of a commit, --version 6, --json
fir plan diff 469 v2 v3, fir plan versions 469	Compare versions; list them with their change kinds
fir plan history 469	Implemented by: its pull requests and commits; --item 1.2
fir plan progress 469	Items and criteria with their states and proofs
fir plan as-built --draft	Draft this pull request’s As built entry from your notes
fir plan policy	What Requires a plan asks of this change; --path
fir plan ready 469	Run readiness on the draft and print the report
fir plan checks 469	The check suite of a version, by stage, and both gates; --version 4, --phase P18, --stage model, --force-model runs a held model check as advisory, --json
fir plan checks add 469 --want <words>	Propose a check compiled from a want in words: its form, stage, cost per run and a backtest; a person accepts it
fir plan loop 414	Start a loop on a draft: --phase P18, --target 95, --budget 4, --program acme/drafts
fir plan loop view lp-4c2e	A loop’s turns, findings, stop reason and final pass; --turns, --json (show stays an alias)
fir plan loop funds 529, fir plan loop defaults --class R2	Why a loop did not run or paused for funds, with the one action; the versioned loop defaults and the report behind them
fir plan elevate 529 --show	The elevation report; fix, ask, accept-risk, out-of-scope or dismiss an improvement
fir plan questions --mine	Your questions across plans by value; --assumptions lists the labeled assumptions
fir plan questions --explain CQ9	A question’s value, source and why it was asked
fir plan assumptions sources	Assumption sources: each test’s state, shadow, on or stopped
fir plan loop stop lp-4c2e --reason <why>	Stop a loop; people and the loop’s starter only
fir plan learned	Learned checks with their source, backtest, state and catch rate; --state shadow, --explain <check>
fir plan score 469	The plan score, its parts and every lost point; --explain
fir plan review 469 --cold	A cold review by other model families; --depth, --strictness, --estimate prints the cost first
fir plan answer 463 CQ1 --text <answer>	Answer a question from the checks or the cold review
fir plan talk 463	A planning session on the draft, by text or with --voice
fir plan summary 469	The plan’s summary card and its short narrative; --since v4·1 shows what changed
fir find <query>	Any plan by key, item, path, symbol, milestone, decision, person or free text, each with its card; --path
fir way show	The version of Frazer’s way a plan runs under, its overlays and what changed; --diff 2.0 2.1
fir plan request-approval 469	Readiness, then routing: prints the route, the approvers and the SLA
fir plan approvals	Approvals waiting; --mine, --batchable
fir plan approve 469 --version 4	Approve a version, for people only; --condition, --answer D2=recommended
fir plan terms 469	The terms of a version; --diff v3 v4 with the change kind
fir plan checklist 469	The current step’s checklist with its evidence; --layer 482
fir plan dispatch 469	Dispatch rows with their filters and scores; --explain 1.5
fir plan accountability 469	Every act on the plan, with the accountable person and the actor
fir plan risk 469 --explain	The risk class, the facts and rules behind it, and the route
fir plan outcome 469	Proofs, measured success metrics and the outcome
fir plan pause 469, fir plan resume 469	Pause a plan (queued merges hold, agents stop at their next step), or resume it
fir plan loop list	Loops on plans: --plan, --state running, stopped or not-run, --mine

Decisions

Command	What it does
fir decision list --plan 469	A plan’s decisions; --open, --json
fir decision view 469 D2	A decision, as its card shows it; fir decision view ADR-0034 for a decision record
fir decision raise --plan 469	Raise a decision row: --question, --option A="6 s", --recommend A, --why
fir decision panel 469 D2	The panel’s opinions on a decision; --deeper runs a deep panel, --estimate prints its cost first
fir decision confidence 469 D2 --explain	The confidence of each option, with its basis and calibration
fir decision lineage ADR-0031	How a decision evolved; --level reasons, brief or redline prints what a session receives at that level, refused above your ceiling
fir decision groups --mine	Your decision groups: what each covers, its crux and its one action; --json
fir decision answer-group <group>	Answer a decision group, for people only, --option A --words <why>; refused for R3 and one-way doors
fir decision track-record	A scope’s reliability diagram, Brier score and counts; --project acme-production
fir decision precedents 469 D2	Up to five precedents, binding or persuasive
fir decision check 469 D2 --option A	Conflicts of an answer with the decisions in force
fir decision answer 469 D2 --option A	Answer, for people only; --words records why
fir decision defer 469 D2 --until <date or event>	Defer, for people only; what it blocks keeps holding
fir decision supersede ADR-0031 --by <decision record>	Supersede a decision in force, for people only
fir decision in-force --paths <paths>	The decisions in force for paths; --as-of main@48195 as of a commit
fir decision history	The decision history; --since 90d, --origin approval
fir decision outcome 469 D2	The decision’s outcome and its scored predictions
fir decision rule create	An auto-apply rule, for people only: --scope, --when "confidence >= 0.90", --shadow
fir decision rule simulate <rule>	Replay a rule on past decisions: what it would have applied and missed; --since 90d
fir panel view <panel>, fir panel replay <panel>	A panel’s members, depths and budgets by use; a draft panel replayed on the last 90 days
fir decision talk	Answer your queue by conversation (--mine, --plan, --query, --voice, --resume); --format ndjson streams the turns
fir principle list, view, keep, edit, drop, export, import, forget	Your principles, by --scope personal, team or org
fir dictionary list, add, remove	The dictation dictionary, personal or for the organization

Person tasks

Command	What it does
fir person-task list --for @me	The person tasks you owe, grouped by vendor and kind, with act by and what each blocks
fir person-task view PT-21453	A task: why, what the agent tried, what was prepared, the steps, its check and its history (show stays an alias)
fir person-task request	Request a person task: its kind, needs, why, what was prepared, the handover, the check and what was tried
fir person-task delegate PT-21454 --to diego	Hand a task to someone who holds the permission its kind needs
fir person-task check PT-21453	Run the kind’s check again
fir person-task removals, stats	What would remove the most person tasks; the metrics by kind, vendor and plan

fir pt is the short form of fir person-task: fir pt view PT-0031.

Milestones

Command	What it does
fir milestone view 50	Progress written by merges, the forecast with its inputs, at-risk reasons
fir milestone update 50 --draft	Draft an update with a citation per sentence; a person posts it

Sessions and progress

Every agent’s work is a Fir session: one record, kept by Fir, for any agent. An agent’s commit needs an open session.

Command	What it does
fir session open	Open a session: --plan and --item, --workspace, --task, --issue or --queue; --harness and --native-id link the harness’s own session
fir session append	Append a harness’s events from a file or stdin, idempotent by event ID
fir session heartbeat, checkpoint, close	Keep it alive; write a checkpoint (--handoff -); close with --outcome done, handed_off or abandoned
fir session resume <session>	Resume one session (--harness, --on here or --on frazer); --mine --open resumes every open one after a restart
fir session fork, attach, import, export	Fork at an event; attach to a commit, pull request or item; import a harness’s past sessions; export a bundle
fir session list, view, search, read, doctor	Sessions with a count line; one session; search events; read a handle; why a write was refused
fir context ack <notice>	Acknowledge a material notice, so the next layer can open
fir item list 469	A plan’s items with their states, claims and blocks; --claimed-by @me, --blocked
fir item claim 469/1.4, fir item release 469/1.4	Take or give up an item’s lease
fir item block 469/1.4 --reason <text>	Mark an item blocked, with the reason
fir steps set -f steps.json	Set your own steps, the whole list at once
fir note add 469/1.4 <text>	An append-only note on an item; --evidence ci:48211
fir assert <statement> --evidence <ref>	An assertion Fir confirms or refutes against its records
fir handoff write, fir handoff show	Write the handoff for the next session; show a session’s last one
fir resume <session>	A session’s bearings in one read: binding, changes, handoff, workspace, CI, claims
fir session rewind <s> --to <event>	Go back to an event: one event, the old branch kept, the workspace restored
fir session verify <bundle>, fir session redact <s>	Check an exported bundle offline; erase a person’s data from a session and every copy, with a receipt

Owners, rules and provenance

Command	What it does
fir owners <path>	Who owns a path, from OWNERS files and from who changed it
fir rules explain 482	The rules that apply to a pull request, and why
fir provenance main@48213	The source attestation of a commit; for a pull request (fir provenance '#482'), what its sessions were given, read and cited, what it changed, linked, proved and had approved; --format prov-json or in-toto
fir link <#PR or commit> <record>	Link a pull request or commit to its plan

Issues

Command	What it does
fir issue	Issues: create (with --evidence), view, list and the rest (Issues)
fir issue evidence add, list, verify, rerun	Attach evidence with a role; list it; check digests and signatures; run a source again
fir issue claim, repro, proof, verify, attempts	The fix agent’s claim, reproduction, proof, production verification and attempts
fir issue policy view, backtest, edit	The issue policy, and what it would have done in the last 14 days
fir issue evidence export 4711 --bundle, fir issue evidence verify --custody	An evidence bundle in open formats; check a bundle or the custody log offline
fir issue view @latest, @top, @mine	The newest issue, the top of the triage order, or yours
fir discussion	Discussions
fir board	Boards

The CLI itself

Command	What it does
fir help --json	Help as data: --level names, summary (the default) or full; fir pr merge --help --json is one command’s card
fir schema <command>	The JSON Schema of a command’s output; --input for its request
fir agent setup <harness>	Connect an agent of any vendor to Fir: its MCP entry, hooks, a short skill and two lines for the instruction file; --dry-run, --scope user or repo
fir doctor	Check sign-in, the warm path, versions, agent detection and the harness setup, with next for each failure
fir daemon start, stop, status	The optional warm path, fird
fir acp -- <agent command>	Run an ACP agent behind Fir’s proxy, recording every session update
fir help search "<words>"	The best commands for a sentence, from a local index, with no model and no network
fir version --json	The version, the contract and the optional behaviors this binary implements (capabilities)
fir shims status, on, off	The guidance shims: inside a Fir workspace, git and gh reads answered by Fir, writes refused with the fir command

Tools around Fir

Command	What it does
fir mcp --toolsets pull_requests,search --read-only	Run a local MCP server with only the tools you name
fir describe	A version string in the shape git describe prints
fir export	Write the repository out as a plain git repository

Environment

Every Fir workspace shell, and every CI task that asks for them, has these variables, so build tools that ask git for a version can read them instead:

Variable	Value
FIR_COMMIT	The commit ID
FIR_BRANCH	The branch
FIR_SEQ	The sequence number, once the commit is merged
FIR_PR	The pull request number and version
FIR_CHANGE_ID	The pull request’s stable internal key

For agents

Use fir, not git, inside a Fir workspace. Read flags from fir <command> --help rather than from memory, add --json when you parse output, and run a change with --dry-run first. The step-by-step task shows the whole path from a workspace to a merge.

Related

• Fir: the words, the workflow and merging
• CLI: the frazer command line, including frazer source repositories import and export
• Frazer for agents