---
title: "Fir CLI"
description: "Every fir command, grouped by job, with what it does, the flags agents use most, the environment it sets and how it behaves in scripts."
url: https://frazer.ai/docs/source/reference/cli
index: https://frazer.ai/docs/source/llms.txt
tokens: 7859
---

> For agents: this page is indexed at https://frazer.ai/docs/source/llms.txt, and every page at https://frazer.ai/llms.txt. Copy commands from this file exactly.

# Fir CLI

`fir` is the command line for [Fir](https://frazer.ai/docs/source), 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](https://frazer.ai/docs/for-agents/cli) 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](https://frazer.ai/docs/source/stacks)).

| 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](https://frazer.ai/docs/source/plans). 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](https://frazer.ai/docs/sessions): 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](https://frazer.ai/docs/source/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](https://frazer.ai/docs/for-agents/tasks#open-a-pull-request-on-fir) shows the whole path from a workspace to a merge.

## Related

-   [Fir](https://frazer.ai/docs/source): the words, the workflow and merging
-   [CLI](https://frazer.ai/docs/cli): the `frazer` command line, including `frazer source repositories import` and `export`
-   [Frazer for agents](https://frazer.ai/docs/for-agents)

## Pages in Reference

- [CLI](https://frazer.ai/docs/cli.md)
- [CLI commands](https://frazer.ai/docs/cli/commands.md)
- [Fir CLI](https://frazer.ai/docs/source/reference/cli.md) (this page)
- [API](https://frazer.ai/docs/api.md)
- [MCP](https://frazer.ai/docs/mcp.md)
- [Errors](https://frazer.ai/docs/errors.md)
- [Example values](https://frazer.ai/docs/example-values.md)