Command reference (fa)¶
Every command of the fa tool. fa <command> --help shows the same. Commands that change files accept --dry-run (show the changes, write nothing); --json prints machine-readable results (what AI agents read through fa mcp). Exit codes: 0 success, 1 a build or check failed, 2 usage or configuration error.
| Command | What it does |
|---|---|
fa audit-print |
printed font/line sizes of figures on a page preset |
fa baseline |
record/check compendium output hashes (check|record [--build]) |
fa build |
analysis -> publish -> verify for projects |
fa bundle |
data bundles: check them against their contract, or list the contracts |
fa claims |
numbers typed by hand into figure legends (they go stale when data changes) |
fa diff-figure |
what changed in a figure since a storyline snapshot or a saved record |
fa export |
package a published figure as an RO-Crate (files, source data, provenance) |
fa impact |
which published figures used a given file or folder |
fa ingest |
add a data bundle to a project: check it, write its full plots block, build |
fa init |
make a project repository here (or in PATH): folders, marker, rules, .gitignore |
fa inventory |
regenerate (or --check) docs/reference/renderer_inventory.md |
fa lineage |
a published figure's upstream: outputs <- run <- config <- code <- data |
fa lint |
config keys the build never read, likely typos, and defaults used |
fa list |
list projects |
fa manifest |
consolidate outputs/clean_atlas_manifest.csv |
fa mcp |
serve the fa commands as tools to AI agents (Model Context Protocol, stdio) |
fa new |
create a project (config, analysis script, figure spec, build-list entry) or a renderer (module with its SCHEMA, test, export) |
fa omics |
omics pack: list its modules, renderers, contracts and plot types |
fa param |
renderer parameters: scaffold | explain | sync |
fa preflight |
overlap, clipping and panel-intrusion checks (--projects ...) |
fa promote |
promote an exploratory project to a paper figure, or renumber a paper figure (AGENTS.md 5.2) |
fa reference |
regenerate (or --check) docs/reference/{cli,api,config,gallery}.md |
fa renderers |
plot names fig_atlas.render() can draw: core, packs and recipes |
fa retire |
move a project to |
fa status |
which published figures are stale (inputs/code/config changed) |
fa storyline |
storyline tools: new | compile [--plan|--all] | init | registry | check | revisions | snapshots | diff | requests | evidence |
fa verify |
completeness checks for one built project |
fa audit-print¶
printed font/line sizes of figures on a page preset
Runs fig_atlas.tools.audit_print_size; its own options: fa audit-print --help.
fa baseline¶
record/check compendium output hashes (check|record [--build])
Runs fig_atlas.tools.figure_baseline; its own options: fa baseline --help.
fa build¶
analysis -> publish -> verify for projects
fa build [-h] [--all] [--dry-run] [--preflight] [--json] [PROJECT ...]
| Argument | Meaning |
|---|---|
projects |
bare project name(s), see fa list |
--all |
every project, then consolidate the master manifest |
--dry-run |
show the steps without running them |
--preflight |
run fa preflight after publishing, before verify (verify then reports its findings) |
--json |
machine-readable result (child output is captured) |
fa bundle¶
data bundles: check them against their contract, or list the contracts
fa bundle [-h] [--all] [--verbose] [--json] {check,contracts} [BUNDLE ...]
| Argument | Meaning |
|---|---|
action |
One of: check, contracts. |
paths |
bundle folder(s) (default with check: every bundle under raw_data/) |
--all |
check every bundle under raw_data/ |
--verbose |
also list bundles and findings at info level |
--json |
machine-readable output |
fa claims¶
numbers typed by hand into figure legends (they go stale when data changes)
fa claims [-h] [--list] [--write] [--check] [--json] [PROJECT ...]
| Argument | Meaning |
|---|---|
projects |
limit to these projects (default: all active) |
--list |
show each hand-typed number in context |
--write |
record the baseline (docs/baselines/hand_typed_numbers.csv) |
--check |
exit 1 if any figure has more than the baseline |
--json |
machine-readable output |
fa diff-figure¶
what changed in a figure since a storyline snapshot or a saved record
fa diff-figure [-h] [--figure FIGURE] [--snapshot RNNN | --against RECORD] [--max-keys MAX_KEYS] [--json] PROJECT
| Argument | Meaning |
|---|---|
project |
|
--figure |
figure number (default 1) Default: 1. |
--snapshot |
storyline snapshot (default: the latest holding the figure) |
--against |
a provenance record file to compare with |
--max-keys |
config keys listed (default 20) Default: 20. |
--json |
machine-readable output |
fa export¶
package a published figure as an RO-Crate (files, source data, provenance)
fa export [-h] [--figure FIGURE] [--out DIR] [--zip] [--include-inputs] [--json] PROJECT
| Argument | Meaning |
|---|---|
project |
|
--figure |
figure number (default 1) Default: 1. |
--out |
crate folder (default outputs/exports/ |
--zip |
also write |
--include-inputs |
copy the raw inputs into the crate (default: list them) |
--json |
machine-readable output |
fa impact¶
which published figures used a given file or folder
fa impact [-h] [--json] path
| Argument | Meaning |
|---|---|
path |
a file or folder, e.g. raw_data/ |
--json |
machine-readable output |
fa ingest¶
add a data bundle to a project: check it, write its full plots block, build
fa ingest [-h] --project PROJECT [--name NAME] [--no-build] [--dry-run] [--json] {bundle} BUNDLE
| Argument | Meaning |
|---|---|
kind |
One of: bundle. |
path |
bundle folder (inputs/ + metadata/metadata.yaml) |
--project |
the project whose config gets the plots block |
--name |
plots. |
--no-build |
skip the confirming build |
--dry-run |
show the config change; write nothing |
--json |
machine-readable output |
fa init¶
make a project repository here (or in PATH): folders, marker, rules, .gitignore
fa init [-h] [--dry-run] [--json] [path]
| Argument | Meaning |
|---|---|
path |
folder to set up (default: the working directory) |
--dry-run |
show the files; write nothing |
--json |
machine-readable output |
fa inventory¶
regenerate (or --check) docs/reference/renderer_inventory.md
Runs fig_atlas.tools.renderer_inventory; its own options: fa inventory --help.
fa lineage¶
a published figure's upstream: outputs <- run <- config <- code <- data
fa lineage [-h] [--figure FIGURE] [--json] PROJECT
| Argument | Meaning |
|---|---|
project |
|
--figure |
figure number (default 1) Default: 1. |
--json |
machine-readable output (the full record) |
fa lint¶
config keys the build never read, likely typos, and defaults used
fa lint [-h] [--defaults] [--verbose] [--max-keys MAX_KEYS] [--check] [--hardcoded] [--write] [--json] [PROJECT ...]
| Argument | Meaning |
|---|---|
projects |
limit to these projects (default: all active) |
--defaults |
list the keys that fell back to Python defaults |
--verbose |
list every unread key |
--max-keys |
unread keys listed per project (default 15) Default: 15. |
--check |
exit 1 if a likely typo is found |
--hardcoded |
instead: literal style values (fontsize=7, ...) in renderers and analysis scripts |
--write |
--hardcoded: record the baseline |
--json |
machine-readable output |
fa list¶
list projects
fa list [-h] [--archived] [--json]
| Argument | Meaning |
|---|---|
--archived |
include retired (archive/) projects |
--json |
machine-readable output |
fa manifest¶
consolidate outputs/clean_atlas_manifest.csv
Runs fig_atlas.tools.consolidate_manifest; its own options: fa manifest --help.
fa mcp¶
serve the fa commands as tools to AI agents (Model Context Protocol, stdio)
fa mcp [-h]
fa new¶
create a project (config, analysis script, figure spec, build-list entry) or a renderer (module with its SCHEMA, test, export)
fa new [-h] [--package PACKAGE] [--plot-type PLOT_TYPE] [--doc DOC] [--from RENDERER] [--domain DOMAIN] [--category {exploratory,paper}] [--raw-root RAW_ROOT] [--slug SLUG] [--dry-run] [--json] {project,renderer} name
| Argument | Meaning |
|---|---|
kind |
One of: project, renderer. |
name |
project name (lower-case letters, digits, -) or renderer name (a Python name: letters, digits, _) |
--package |
renderer: the package it goes in (default the core; a pack only for a field-specific shape) Default: fig_atlas.renderers. |
--plot-type |
renderer: bundles with this plot_type are drawn by it (fa ingest bundle) |
--doc |
renderer: one line on what the plot shows (module docstring) |
--from |
renderer: start from a copy of this existing renderer (fa renderers; the gallery shows each) instead of the placeholder scatter plot |
--domain |
namespace domain, e.g. lab (omit with --category for a flat sandbox project) |
--category |
namespace category One of: exploratory, paper. |
--raw-root |
input bundle folder (default raw_data/ |
--slug |
figure 1 slug used in file names (default main) Default: main. |
--dry-run |
show the files and diffs; write nothing |
--json |
machine-readable output |
fa omics¶
omics pack: list its modules, renderers, contracts and plot types
fa omics [-h] [--json] {list}
| Argument | Meaning |
|---|---|
action |
One of: list. |
--json |
machine-readable output |
fa param¶
renderer parameters: scaffold | explain | sync
fa param [-h] [--apply] [--max-keys MAX_KEYS] [--include-computed] {scaffold,explain,sync} RENDERER|PROJECT [key]
| Argument | Meaning |
|---|---|
action |
One of: scaffold, explain, sync. |
target |
a renderer (scaffold) or a project (explain, sync) |
key |
explain: dotted config key, e.g. plots.volcano.lfc_min |
--apply |
sync: write the keys (default: show them) |
--max-keys |
sync: skipped keys listed per reason Default: 8. |
--include-computed |
sync: also write defaults the renderer computes (freezes today's value) |
fa preflight¶
overlap, clipping and panel-intrusion checks (--projects ...)
Runs fig_atlas.tools.preflight; its own options: fa preflight --help.
fa promote¶
promote an exploratory project to a paper figure, or renumber a paper figure (AGENTS.md 5.2)
fa promote [-h] --figure FIGURE --slug SLUG [--supp] [--no-build] [--dry-run] [--json] PROJECT
| Argument | Meaning |
|---|---|
project |
|
--figure |
figure number in the storyline |
--slug |
short name: |
--supp |
a supplementary figure (...-paper-supp-fig |
--no-build |
skip the confirming build |
--dry-run |
show the moves and diffs; write nothing |
--json |
machine-readable output |
fa reference¶
regenerate (or --check) docs/reference/{cli,api,config,gallery}.md
Runs scripts/make_reference.py; its own options: fa reference --help.
fa renderers¶
plot names fig_atlas.render() can draw: core, packs and recipes
fa renderers [-h] [--json]
| Argument | Meaning |
|---|---|
--json |
machine-readable output |
fa retire¶
move a project to
fa retire [-h] [--no-build] [--dry-run] [--json] PROJECT
| Argument | Meaning |
|---|---|
project |
|
--no-build |
skip the confirming build |
--dry-run |
show the moves and diffs; write nothing |
--json |
machine-readable output |
fa status¶
which published figures are stale (inputs/code/config changed)
fa status [-h] [--all] [--check] [--json] [PROJECT ...]
| Argument | Meaning |
|---|---|
projects |
limit to these projects (default: all) |
--all |
also list the fresh figures |
--check |
exit 1 if any figure is stale |
--json |
machine-readable output |
fa storyline¶
storyline tools: new | compile [--plan|--all] | init | registry | check | revisions | snapshots | diff | requests | evidence
Runs fig_atlas.tools.storyline; its own options: fa storyline --help.
fa verify¶
completeness checks for one built project
fa verify [-h] [--json] PROJECT
| Argument | Meaning |
|---|---|
project |
|
--json |
machine-readable output |