Skip to content

Verbs

The verbs by extension

fm composes these verbs from the base, the plugins the project mounts and the repository's own tasks file, and an extension's verbs are in its section below; fm <verb> --help describes one.

  • livery.workshop: abandon, caches.clear, check, ci.balance, ci.cancel, ci.dispatch, ci.e2e, ci.footprint, ci.logs, ci.profile, ci.rerun, ci.run, ci.scale, ci.status, ci.timings, clean, commit, devenv.down, devenv.ls, devenv.rm, devenv.up, drift, drift.check, env.check, env.emit, env.set, env.show, examples, explain, extensions, format, graph.affected, integrate, issue, issue.close, issue.comment, issue.create, issue.list, issue.reopen, issue.search, issue.show, issue.stop, issue.update, layering, layering.base-imports-no-extension, layering.graph, layering.sibling-references, lint, lock, new.package.workshop-extension, new.project, provenance, release.verify, run, shell, speed.accept, start, status, store.ls, store.show, submit, submit.arm, submit.disarm, submit.merge, sync, test, toolroom.add, toolroom.lock, toolroom.restub, toolroom.sync, typecheck, typecomplete, workflow.abort, workflow.release, workflow.release.dispatch, workflow.update, workflow.update.dependencies
  • footman.doctor: doctor
  • footman.janitor: janitor
  • footman.self: self.add, self.install, self.path, self.remove, self.uninstall
  • livery.footman: footman.pages
  • livery.forge: forge.conformance, forge.dev.down, forge.dev.restart, forge.dev.seed, forge.dev.up, forge.fixtures.record
  • livery.toolroom.bench: toolroom.artifacts, toolroom.assemble, toolroom.audit, toolroom.color, toolroom.docs, toolroom.gather, toolroom.goldens, toolroom.index.build, toolroom.list, toolroom.owed, toolroom.pages, toolroom.prime, toolroom.provision, toolroom.read, toolroom.refresh, toolroom.spec, toolroom.verify, toolroom.verify-host

Each extension the workspace installs, listed or required by one listed, has a block below: what it does, its verbs, its templates, the contract keys and step options it reads, and the installed extensions it contributes to. A package turns any step off with enabled = false in its [phases.<phase>.<step>] table.

basedpyright

The type checker basedpyright, warnings as errors, over the python files the root pyrightconfig.json names, and a step that judges every public API type-complete, which a workspace turns on.

item kind what it does
fm typecheck.basedpyright verb Run the typecheck.basedpyright step alone, over the named paths or the workspace; the words after -- go to its tool.
fm typecomplete.basedpyright verb Run the typecomplete.basedpyright step alone, over the named paths or the workspace; the words after -- go to its tool.
[phases.typecomplete.basedpyright] enabled = true root contract switch turns on the step, which the extension declares off

changelog

Each package's CHANGELOG.md: at each release, git-cliff writes the entry from the commits since the package's last release tag, as the package's cliff.toml says.

clang-format

The C and C++ formatter clang-format, judging each C or C++ package against the style in its .clang-format; under --fix it rewrites the files.

item kind what it does
fm format.clang-format verb Run the format.clang-format step alone, over the named paths or the workspace; the words after -- go to its tool.

clang-tidy

The C and C++ linter clang-tidy, judging each C or C++ package against the checks in its .clang-tidy and the compilation database its build writes.

item kind what it does
fm lint.clang-tidy verb Run the lint.clang-tidy step alone, over the named paths or the workspace; the words after -- go to its tool.

claude

What Claude Code reads in a workspace: CLAUDE.md, the guidance under .workshop/fragments/, and the skills, hooks and settings under .claude/, with the hook verbs those settings run.

coverage

Each package's coverage floor, judged on the union of what every CI leg measured, the record that carries it across runs, and the site's coverage pages. It stays dormant until a listed extension measures for it.

item kind what it does
fm coverage.accept verb Lower a package's coverage mark deliberately, with the reason on the record.
fm coverage.enforce verb Enforce every package's floor on the measured data here.
[coverage] package contract key the package's coverage policy
[coverage] floor package contract key the coverage the package keeps: a percentage, or auto-ratchet for the mark its CI runs record; 100 when absent and the package has tests
[coverage] epsilon package contract key how far, in percentage points, coverage may fall below the floor; 0.5 when absent
[coverage] required package contract key whether anything judges the package's coverage; true when absent, and false gives no verdict, records no mark and takes no floor

Contributes to docs and python.

docs

The documentation site: its verbs build, serve and publish it from the workspace's docs/ and each package's docs/, and a lint step judges the links in the authored pages.

item kind what it does
fm docs.build verb Mount every package's docs, assemble the config, and build the site, strict.
fm docs.publish verb Run the deploy phase on the built site, then publish it through the seam.
fm docs.serve verb Mount every package's docs and serve the site live.
fm lint.doclinks verb Run the lint.doclinks step alone, over the named paths or the workspace.
[docs] root contract key the documentation site: its address, its title, its description and where it publishes
[docs] site-url root contract key the site's public address, ending in a slash, for its canonical links, its llms.txt and the task links in --help, --list and --json rows; no task links when absent
[docs] title root contract key the site's title; the project's name when absent
[docs] description root contract key the site's one-line description
[docs] publish root contract key where the site publishes; the forge's default when absent: pages on GitHub and GitLab, a container on Gitea
[docs] package contract key how the site documents the package
[docs] api package contract key whether the package's modules get API reference pages; true when absent
[docs] generators package contract key the verbs that write the package's pages: a verb's name, or a table with the system packages it needs
[docs] generators[] package contract key one generator: a verb's name, or a table with the verb, the system packages it needs and the paths it writes
[docs] generators[].verb package contract key the verb, a task the package ships
[docs] generators[].requires package contract key the system packages the verb needs on a docs machine
[docs] generators[].outputs package contract key the paths the verb writes outside the generated trees, each relative to the root, a directory ending in /, or package/ for the path in each package; a build after no listed generator declares one removes it; none when absent
[docs] name package contract key the package's place in the site's Packages tree, a dotted path whose last part is its label: workshop.extensions.ruff; its shallowest import path less the namespace every package shares, or its folder under packages/, when absent
[docs] coverage package contract key the static coverage reports the package's own tooling writes
[docs] coverage[] package contract key one report: its name on the page and its directory
[docs] coverage[].label package contract key the report's name on the page
[docs] coverage[].path package contract key the report's directory, relative to the package
[docs] extra-css package contract key stylesheets for the package's pages, relative to its docs/
[docs] extra-javascript package contract key scripts for the package's pages: a path, or a table with its attributes
[docs] extra-javascript[] package contract key one script: a path, or a table with its path and the script element's attributes
[docs] extra-javascript[].path package contract key the script, relative to the package's docs/
[docs] extra-javascript[].type package contract key the script element's type
[docs] extra-javascript[].defer package contract key whether the script runs after the page parses
[docs] extra-javascript[].async package contract key whether the script runs as soon as it loads
[phases.docs.task-reference] enabled = true root contract switch turns on the step, which the extension declares off

mkdocstrings

The python API reference on the docs site, a page per module, and the lint steps that judge the docstrings it publishes and the cross-references in them.

item kind what it does
fm lint.docrefs verb Run the lint.docrefs step alone, over the named paths or the workspace.
fm lint.docstrings verb Run the lint.docstrings step alone, over the named paths or the workspace.
[phases.docs.mkdocstrings] paths package step option, strs, default [] the directories, relative to the package, the python handler also reads modules from, after its sources

mypy

The type checker mypy, run once for each of linux, darwin and win32, over the python files the root mypy.ini names.

item kind what it does
fm typecheck.mypy verb Run the typecheck.mypy step alone, over the named paths or the workspace; the words after -- go to its tool.

pyrefly

The type checker pyrefly, over every platform at once, on the python files the root pyrefly.toml includes.

item kind what it does
fm typecheck.pyrefly verb Run the typecheck.pyrefly step alone, over the named paths or the workspace; the words after -- go to its tool.

pytest

The test runner pytest: each python package's suite and its documentation examples, run in the workspace's environment. While coverage is listed, it measures every python suite for it.

item kind what it does
fm examples.pytest verb Run the examples.pytest step alone, over the named paths or the workspace; the words after -- go to its tool.
fm test.pytest verb Run the test.pytest step alone, over the named paths or the workspace; the words after -- go to its tool.
[phases.test.pytest] parallel package step option, bool, default true run the package's suite across cores; false runs it under -n 0

Contributes to coverage.

python

Python distributions: each package's version stamped, its wheel and sdist built, published and verified, its suite run against the installed wheel, and the layering rules over the python sources. Its run phase starts the scripts a pyproject.toml names.

item kind what it does
fm layering.declared-imports verb Run the layering.declared-imports step alone, over the named paths or the workspace.
fm layering.private-reaches verb Run the layering.private-reaches step alone, over the named paths or the workspace.
fm layering.runner-terminal verb Run the layering.runner-terminal step alone, over the named paths or the workspace.
fm new.package.python-library <name> template a python library: a typed module, its tests, a pyproject.toml uv builds, and with --command a script on PATH
fm new.package.python-library --command template option, str, default "" the name of a script on PATH that runs the package's main(); none by default
[python] root contract key the python extension's settings for the workspace
[python] private-reaches root contract key each reach into another distribution's private name the private-reaches rule allows, with its reason; an entry no source uses any more refuses
[python] private-reaches[] root contract key one allowed reach: the distribution that reaches, the private it reaches, and why
[python] private-reaches[].from root contract key the distribution whose source reaches
[python] private-reaches[].reaches root contract key the private it reaches, by its dotted path
[python] private-reaches[].reason root contract key why the reach stays, and the public seam that will replace it

Contributes to pytest.

ruff

The python formatter and linter ruff, over the python files they claim and each conan package's recipe, configured by the root ruff.toml; under --fix they rewrite the files.

item kind what it does
fm format.ruff verb Run the format.ruff step alone, over the named paths or the workspace; the words after -- go to its tool.
fm lint.ruff verb Run the lint.ruff step alone, over the named paths or the workspace; the words after -- go to its tool.

ty

The type checker ty, over every platform at once, on the python files the root ty.toml includes.

item kind what it does
fm typecheck.ty verb Run the typecheck.ty step alone, over the named paths or the workspace; the words after -- go to its tool.