API reference¶

Say where a task is offered: @expose("global_only").

The decorator spelling of @task(expose=…), for authors who prefer the gates above the signature — it sets the same one answer, so stacking it twice is a contradiction rather than an addition, unlike @requires_*.

@task
@expose("global_only")
def new(name: str): ...

Gate a task on a live predicate — available only while it is truthy.

The generic gate the three specialisations build on. A predicate that raises reads as unavailable, the exception named:

@task
@requires(lambda: Path("config.toml").exists(), reason="needs config.toml")
def publish(): ...

Gate a task on Python modules being importable (find_spec, no import).

Keep the real import in the body; this only checks availability, so a missing optional dependency lists as a clean reason, never an import crash.

Gate a task on command-line tools being on PATH (shutil.which).

Gate a task on environment variables being set (in os.environ).

Run a command or a Python callable in the current task's context.

Subprocess output is decoded as UTF-8 by default; pass encoding= for a tool that speaks another code page, or encoding=None for the locale default. Ignored for callables (in-process, no bytes boundary).

input= feeds the child's standard input and closes it — the one lane a payload can't take through argv (uv pip install -r - reads its requirements there). A string, encoded the way the capture is decoded (encoding=). The read side of the process boundary is a task parameter marked stdin; this is the write side, so a task can sit in the middle of a pipeline without a shell between it and either neighbour. An in-process tool has no standard input to feed — input= on one is a taught TypeError.

cwd= roots this one call somewhere other than the task's directory; rel= appends a relative suffix to the base in force (ctx.cwd, or the explicit cwd=), so run("npm run build", rel="web") is the ergonomic spelling of cwd=ctx.cwd / "web". cwd="unmanaged" opts this one call out instead — the task-level token, per call: a subprocess spawns inheriting the live process cwd, an in-process callable runs under it — for a call that touches no paths while its task keeps ctx.cwd everywhere else.

color= decides what this one child emits: "always" forces the colour variables into its environment, "never" writes NO_COLOR and removes any inherited force variables (a tool reading mere presence would honour one straight past NO_COLOR), and the default "auto" follows the run's own decision. Explicit beats ambient, so color="always" holds under an exported NO_COLOR. It merges on top of env= when both are given, and the in-process lane's overlay reads it too — so a per-call colour reaches both halves of a tool's colour, its flags and its environment, through one door. footman's own chrome (the step lines) stays on the run-wide decision: this is about the child's bytes, not the frame around them.

recorded=False runs this call off the record. A call is a step by default: it earns a receipt line, a row in --json, a recording() entry, and its output joins the task's block. Some calls aren't part of the task's story, though — they are how a task knows something (git rev-parse HEAD in a release task). Those return their Result and report nothing: no record, no receipt, no output replayed.

Everything else still applies, because the call is not unmanaged — only unreported. It runs in ctx.cwd with ctx.env, inside the task's lane, with colour resolved the same way, it is terminated with the rest on a fail-fast, and it still raises unless nofail=True. It also executes under recording(), where a step would be faked — unless the recording carries a scripted answer for it (recording(answers=…)), in which case the script wins: a value read is not the story being recorded, and faking it would corrupt the story that is — the real steps downstream would record whatever a blank answer produced.

pre_record= reviews the record before it is sealed. Some tools speak exit codes that need interpreting — djlint --reformat exits 1 when it changed files, which is success for a formatting gate. The reviewer receives the draft (ResultView) after the work ran: it reads what was captured and may set title and code; the receipt, the record, and the raise-on-nonzero decision all read what the review leaves behind, so the call site writes no nofail=. A reviewer that raises fails the call with its own error — a broken reviewer is a broken gate — and the record keeps what the work honestly produced. Dry-run never reviews (nothing ran, nothing captured), and a recorded=False call has no record to review (a note, not an error).

In-process work is a step now: run() runs commands. Lift a callable instead — @step / step(fn, title=…) builds an item that earns a receipt, and with step("…"): records a block where it stands. (toolroom keeps its in-process lane through its own private channel.)

_show is an internal channel from toolroom's bridge: a structured view of the call, so the shown command line can be normalised and role-coloured while execution runs whatever the tool needs. An explicit title still wins; a direct run([...]) is unaffected.

Run tasks and steps concurrently; wait; fail if any fail.

Each one runs in a child of the current context with its own output buffer, flushed atomically on completion so concurrent output never interleaves. Pass task functions directly (parallel(lint, typecheck)) and built step items for everything else — parallel(convert(images)), or parallel(step(fn)(args)) for a function you didn't write. A bare zero-argument maker is welcome too: parallel(clean) builds and runs clean().

Nothing anonymous runs: footman only schedules, records, and safely cancels work it owns, and a bare callable is a stranger — no name for the report, no place in the plan, no way to stop it cleanly. The lift is one word, and it buys the step a receipt.

With no arguments it is a block instead, and the calls inside it are the fan-out — written as ordinary calls, with their values afterwards:

with parallel() as p:
    build("web")
    p(step(shutil.rmtree)(tmp, ignore_errors=True))
web, cleaned = p.results

Inside the block a task call is queued, so it has no value there (using one is a taught error); a built step item joins through p(item); everything runs when the block ends, under the same rules — sharing, hooks, -s/-j.

One name, three positions: @step on a def, with step("title"): over a block, step(fn, title=…) around a function you didn't write.

Decorator and expression positions are the same expression, so both return the maker — calling it builds the item; nothing runs until something executes it (parallel(), or calling the built item).

Attach a reviewer to a task: @pre_record(fn) stacked on the def.

The reviewer receives the task's record while it is still a draft — after the body concluded, before the record is sealed, observed, or reported. It reads the draft (a ResultView) and may set title and code; the row's verdict follows what the review leaves behind, and the record's audit names the reviewer and what it did.

Reviewers run from the inside out: the hook written closest to the function sees the draft first, and each one above it sees what the previous reviewers left. Stacks above or below @task alike — the decorated function (and a TaskFn when stacked above the lifter) keeps its static type. A reviewer that raises fails the task with its own error: a broken reviewer is a broken gate.

Arguments after -- on the command line, for the running task.

The task this one shadows in the cascade — footman's super().

A nearer tasks.py overriding a task by name usually wants to extend it, not replace it. Call this inside the overriding task's body to get the task it shadows, then call that like the plain function it is:

# svc/api/tasks.py — the root also defines `check`
@task
def check(fix: bool = False, contracts: bool = True):
    inherited()(fix=fix)          # arguments are forwarded explicitly
    if contracts:
        run("./verify-contracts.sh")

Forwarding is deliberately manual: the two signatures are independent (a leaf usually adds a parameter), so automatic forwarding could only drop arguments silently or fail at run time — where spelling the call out shows you the mismatch as you type it. Being an ordinary call, it also runs to completion before the next statement — and composes with parallel(inherited(), extra) when you want otherwise.

fm --where <task> lists the whole shadow chain; fm --help <task> shows the inherited task's options, so you can read the forwarding call straight off it.

Fail the current task with a reason (and exit code, default 1).

The blessed way to stop a task deliberately: fail("no open PR to act on"), or fail("reserved branch", code=3) to pick the exit code too. A function, not a raise, on purpose — a task lives in your repo under your linter, and raise SomeError("a literal") trips flake8-errmsg (EM101) and tryceratops (TRY003) at the call site, every failure. A call trips neither, the same reason sys.exit() and pytest.fail() are functions. return N still spells a bare code; sys.exit(...) still works — fail() is just the footman-native one, with a reason and a code together.

fail() means failure, so code=0 — success — is a contradiction it refuses rather than a corner it interprets: return 0 (or a plain return) spells stopping early with success.

Report this task's own progress: done of total units.

Some work knows exactly how far along it is — 23 of 150 migrations, bytes of a download — and that is better evidence than any duration history. A reporting task's counts drive the live bar directly (counted beats estimated), so the bar is honest on the very first run, where the estimator would still be guessing.

@task
def migrate():
    for i, record in enumerate(records, 1):
        apply(record)
        progress(i, len(records))

A total of 0 (or less) clears the report, returning the run to its estimate. Outside a run, or with no live status line, this is a no-op — plain calls and captured runs cost nothing.

Iterate iterable, reporting progress as it goes.

The ergonomic form of progress(): the total comes from len() when the iterable has one, or from total when you know it for a generator. Without either, iteration still works — the run simply keeps whatever progress it had.

@task
def migrate():
    for record in track(load_records()):
        apply(record)

Time a section of the running task — with footman.section("resolve"):.

Records onto the task's own timeline, subdividing its span; nested blocks nest. For work that overlaps — several waits in flight at once — use stream(), where overlap is legal.

Record an instant on the running task's timeline — a moment worth a label, no duration.

A named parallel timeline under the running task — see Stream.

Ask the person running the task for a line of input.

A bare input() doesn't work in a task: its prompt goes to stdout, which footman buffers per task so parallel output never interleaves (and --json stays one envelope), so the prompt is swallowed and the task looks hung. prompt() writes to the real terminal on stderr instead — never captured — and serialises concurrent prompts.

Usable only inside an @task(interactive=True) task; called in an ordinary task body it raises a taught error naming the two fixes. Off a terminal, under --no-input or --dry-run, or when it would otherwise block, it returns default if given, else raises — an unattended run fails loudly, and a rehearsal is unattended by nature. For a value a script must supply, take it as a task parameter (a CLI flag) instead.

type= reuses the parameter type language as the validator: the answer runs through the same coercion pipeline a flag does — int, Path, an enum, Literal[…], a union, or Annotated[…] carrying between() / check() / exists — and a bad answer is taught and re-asked rather than raised. An empty answer takes default (returned as given, uncoerced), and an unattended run takes it the same way. One value per prompt: collections, and the markers that decide how a parameter gets filled (ask(), env(), suggest(), …), are refused by name — declare a parameter, or reach for select().

secret=True hides the typing (getpass) and returns a Secret, so the answer redacts in tracebacks and structured output the same way ask(secret=True) does — hiding a value while it is typed and then printing it in the first traceback would be a strange kind of secret. A default returned unattended is wrapped too: where the value came from doesn't change what it is. A secret is text by nature, so secret=True with a non-str type= is refused — ask(secret=True) on a typed parameter is that spelling.

Ask a yes/no question. --yes auto-answers yes; Enter alone takes default; off a terminal or under --no-input/--dry-run the answer is default. Guarded like prompt() — interactive tasks only.

Let the person pick from a runtime-computed list — the one interactive case a flag can't cover, because the options aren't known until the task runs (which changed packages to release, which stale branches to delete).

options are strings, or (label, value) pairs to show one thing and return another. multiple=True returns the chosen subset as a list; otherwise one value is returned. Guarded like prompt() (interactive tasks only), and off a terminal or under --no-input/--dry-run it returns default, or raises if none was given.

Whether a prompt would reach a human: stdin is a real terminal and the run was not declared unattended (--no-input, --dry-run).

The question prompt()/confirm()/select() already answer for themselves by degrading to their defaults — attended() is for changing the shape of a run instead: skip an optional wizard outright, take the quiet path in CI. --yes deliberately does not count as unattended: it auto-answers confirm() gates but forbids nothing.

Readable anywhere, but it licenses nothing: a mid-body prompt still requires @task(interactive=True), because owning the terminal under parallelism is a separate question from someone being there to answer.

Whether this run's output lands on a live terminal, colour policy aside: the real stdout is a terminal (on Windows, one that interprets ANSI) and output is not captured into a --json envelope. NO_COLOR and --color do not change the answer — a person with colour turned off is still watching, so gate pagers and live displays here and colour on colored(). False outside a run: the scheduler stamps it per task.

Whether this task's own output should dress for colour — the same never/always/auto cascade footman's own chrome follows: --color=never (or NO_COLOR, or a dumb terminal) says no, --color=always forces colour even into a pipe (but never into a --json envelope), and auto follows the terminal.

The current task's working directory, always concrete.

ctx.cwd as the policy ladder resolved it — the blessed base for a task body's own path arithmetic (footman.cwd() / "dist"), instead of relative paths against the process cwd, which belongs to no one in a parallel run. Outside a run it is simply the process cwd.

Really change the process directory — inside a serial/exclusive task.

The sugar for bodies that own the globals: the default target is the task's own ctx.cwd; arguments follow the marker grammar exactly — a policy token (root, taskfile, asinvoked) or an absolute path, with rel= for a relative suffix; a bare relative path is the same taught error the markers give. Performs a real os.chdir, keeps ctx.cwd in sync (so a nested run() roots where the block does), restores both on exit. In a parallel task it is a taught error — the cwd belongs to no one there.

Declare a named resource to serialise on. One binding per resource: re-declaring a taken name is a refusal naming both sites — reuse is spelled by importing the handle, never by re-declaring. (The same site re-executing — a module re-imported — is the same declaration.)

This CLI's cache directory, created if it isn't there yet.

Derived data, safe to delete: footman's collector sweeps this folder by age, so put nothing here you would mind losing.

(footman.cache_dir() / "index.json").write_text(payload)

Where it lands is the branded CLI's business — its own folder, or ~/.cache/<name> by default. A task asks for the kind of folder it wants and gets one that exists.

This CLI's data directory, created if it isn't there yet.

Durable and machine-local — credentials, tokens, generated assets. The collector never touches it, which is the whole difference from cache_dir(). Created owner-only (0o700), like ~/.ssh, because credentials are exactly what it is documented to hold.

(footman.data_dir() / "credentials.json").write_text(token)

This CLI's config directory — your writing, never footman's.

The user-level config file and the user-level tasks file live here and travel together. Unlike cache_dir() and data_dir() this one is not created on demand: an empty config directory says something different from a missing one, and inventing it would be footman writing where only you should.

The user-level config file — ~/.config/<brand>/config.toml by default. May not exist; a runner with no config is the ordinary case.

The user-level tasks file: the cascade's outermost writable rung, riding every project. May not exist.

The top of this invocation's task cascade, or None outside a project.

The same answer --json reports and the root cwd policy resolves against — never a guess from the current directory, which may be anywhere beneath it.

The command this CLI is invoked as — fm, or a branded CLI's own.

For output that has to call the CLI back: a generated CI workflow, a README line, a task that writes prose naming the command someone will type. A branded runner must emit its own name, or the file it writes tells the reader to run a command they do not have.

(root / ".github/workflows/ci.yml").write_text(
    f"      - run: {footman.prog()} check\n"
)

Inside a task body, prefer ctx.prog — declare a ctx: Context parameter and read it. That is the invocation's own answer rather than process state, and it is what footman's own taskdocs plugin uses. This accessor exists for the code that never receives a context: a plugin building its tree at mount time, a helper called from anywhere.

The distribution that ships this CLI, or None if it never said.

The name someone would pip install — what the uv handoffs reason about, and what self.install puts on a PATH. App(dist=…) sets it; stock footman answers "footman".

None is a real answer, not a gap: declaring a distribution is opt-in for a branded CLI, and saying "footman" for a brand that never declared one would name the wrong package.

Download url (cached), returning the path to the local file.

A second call for the same URL revalidates with the server (ETag / Last-Modified) rather than re-downloading; a 304 Not Modified costs one round trip and keeps "cached" honest. Pass refresh to skip revalidation and fetch unconditionally.

@task
def deps():
    "Fetch the toolchain."
    archive = fetch(TOOLCHAIN_URL, sha256="9f86d0…")
    run(["tar", "-xzf", archive, "-C", "vendor"])

into copies the cached file to a path of your choosing (and returns that path). sha256 verifies what arrived and refuses a mismatch — the way to make a build reproducible. backend overrides the configured one for this call.

Under --dry-run nothing is downloaded: the step is recorded and the would-be cache path returned, so a plan can be inspected safely.

Whether the caller supplied name, as opposed to footman inferring it.

@task
def build(*, profile: Path = Path("build-profile.json")):
    if given("profile"):   # `fm build --profile` writes the default file;
        trace_to(profile)  # `fm build` writes nothing at all

True when the parameter was named on the command line (with or without a value — --profile alone means its default, and means it on purpose), passed as a keyword by a body call, or answered at an ask() prompt. False when the value came from an env() fallback, a default(fn), or the declared default, because nobody asked for those.

That distinction is the only way to tell "the default one, please" from "no opinion", which a value alone cannot express: both hand you the same path.

name is the parameter name, not its flag spelling — dry_run, not --dry-run. Naming something the running task has no parameter for is an error rather than a silent False, since a typo would otherwise read as a perfectly ordinary "not given".

Install ctx as the current run context for the duration of the block.

The public seam for calling tasks from other Python code — tests included: run() and hosted toolroom calls inside the block read this context instead of a fresh default. footman.testing.recording builds on it.

with use_context(Context(env={"CI": "1"})) as ctx:
    deploy()
assert ctx.steps[0].code == 0

Mount a task tree from an importable module — modules only; for an installed package's advertised tasks use plugin().

include("shared_tasks")                    # everything, at root
include("shared_tasks", only=["lint"])     # cherry-pick a child
include("mytasks.lint")                    # one group out of a module
include("mkdocs_helpers.tasks", into="docs")  # namespaced: fm docs.…

The longest importable prefix is imported under a registry capture (the provider's decorators can't leak into your tree); the rest of the string walks the captured tree. Collisions are loud (RegistrationError) unless override=True; your own definitions silently win. Included tasks run from your file's directory — a shared lint task lints this project. A Group or imported module may be passed programmatically (tests, generated trees). Returns the group grafted into.

Mount a task tree from an installed package's footman.tasks entry point — entry points only; for your own modules use include().

plugin("acme.devkit")                      # the import *: every group, top level
plugin("acme.devkit.lint")                 # from acme_devkit import lint
plugin("acme.ci", exclude=["deploy"])      # everything but one child
plugin("footman.docs", into="footman")     # built-ins are ordinary plugins
plugin("acme.linters.default", into="lint")  # adopt a provider's default

The longest installed entry-point name is the identity (consumed at resolve time, retained as provenance); the rest of the string walks the advertised tree. The mounted node lands under its own name — into= (a dotted address, created on demand) is the consumer's placement, and there is no rename. Returns the group grafted into.

Redirect module-level @task/group registration into a fresh tree.

The seam include() uses to import a provider module without letting its decorators land in the current registry: root.tasks/root.groups are swapped for fresh dicts for the duration and the captured tree is yielded. Reentrant — a provider may itself include() another provider.