#pkfire

Typed task runner with Bazel-style incremental caching, configured in Pkl.

#Why pkfire

• Shared inputs ("these 6 globs of .go files feed three different tasks") that you keep copy-pasting.
• Matrix duplication — four near-identical recipes for linux-amd64, linux-arm64, darwin-amd64, darwin-arm64.
• Per-package overrides in a monorepo where every package has a build and test step that differs only in path and toolchain.
• No way to verify the runner config itself — a typo in a task name only fails when you run that task, in CI, on a Friday.

#Install

#Homebrew (Apple Silicon macOS)

brew tap mizchi/pkfire https://github.com/mizchi/pkfire
brew install mizchi/pkfire/pkf

#Install script

curl -fsSL https://raw.githubusercontent.com/mizchi/pkfire/main/install.sh | sh

# pin a version and choose the install dir
curl -fsSL https://raw.githubusercontent.com/mizchi/pkfire/main/install.sh \
  | sh -s -- --version 0.12.0 --dir /usr/local/bin
# env-var form: PKF_VERSION, PKF_INSTALL_DIR, PKF_NO_VERIFY

#Manual download

# pick your target: linux-amd64 | linux-arm64 | darwin-arm64
target=linux-amd64
curl -fsSL -O "https://github.com/mizchi/pkfire/releases/latest/download/pkf-${target}.tar.gz"
tar -xzf "pkf-${target}.tar.gz"
install -m 0755 pkf /usr/local/bin/pkf

#GitHub Actions

# .github/workflows/ci.yml
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: mizchi/pkfire@v0.14.2       # or @v0 to track the latest 0.x
      - run: pkf run ci

Why @v0.5.0 and not @pkfire@0.14.2? GitHub Actions cannot parse uses: <repo>@<ref> when the ref itself contains @ — the whole workflow file fails to load with a generic "workflow file issue" error and zero jobs run. Pkl release tags are pkfire@<ver> for the package URI, so the Release workflow additionally publishes v<ver> and a floating v<major> tag at the same commit. Use those from uses:. For maximum supply-chain safety, pin to the commit SHA directly: uses: mizchi/pkfire@<40-char-sha> # v0.5.0.

      - uses: mizchi/pkfire@v0.14.2
      - run: pkf run ci
        env:
          PKFIRE_REMOTE_CACHE: ${{ vars.PKFIRE_REMOTE_CACHE }}
          PKFIRE_REMOTE_TOKEN: ${{ secrets.PKFIRE_REMOTE_TOKEN }}

#Nix (no toolchain required)

nix run github:mizchi/pkfire -- run hello       # one-shot
nix profile install github:mizchi/pkfire        # persistent

#Quick start

mkdir my-project && cd my-project
pkf init                # writes a starter Taskfile.pkl
pkf run hello           # smoke the generated task

#Authoring a Taskfile

amends "package://pkg.pkl-lang.org/github.com/mizchi/pkfire/pkfire@0.14.2#/Taskfile.pkl"

local build = new Task {
  name = "build"
  cmd = "moon build --target native --release"
  inputs { "src/**/*.mbt"; "src/**/moon.pkg"; "moon.mod" }
  outputs { "_build/native/release/build/main/main.exe" }
}

local test = new Task {
  name = "test"
  cmd = "moon test"
  inputs { "src/**/*.mbt"; "src/**/moon.pkg"; "moon.mod" }
  deps { build }            // direct Task reference, typo-checked by Pkl
}

tasks { build; test }

local ci = new Task {
  name = "ci"
  deps { build; test }
}

local strict = new Task {
  name = "strict"
  shellFlags = List("-eu", "-o", "pipefail", "-c")
  cmd = "pkl format --check ."
}

local nodeSnippet = new Task {
  name = "node-snippet"
  shell = "node"
  shellFlags = List("-e")
  cmd = "console.log(process.argv.slice(2))"
}

cd services/api/internal && pkf run ci    # uses services/api/Taskfile.pkl
cd /repo/root && pkf run ci               # uses /repo/root/Taskfile.pkl

pkf list                       # show public tasks
pkf list --unsorted            # show tasks in Taskfile declaration order
pkf list --all                 # include internal tasks
pkf list --color=always        # force ANSI color (auto, always, never)
pkf list -v                    # add cmd preview and deps
pkf list --json                # machine-readable (for editor / CI tooling)
pkf run test                   # builds first, then tests; second run hits cache
pkf run -j 8 test              # cap parallelism at 8
pkf run --watch test           # re-run on input changes (Ctrl+C to stop)
pkf run --dry-run test         # preview: per-task hit/will-run/uncached status + cmd
pkf run --print-hash test      # print action keys, do not execute
pkf run --explain-cache test   # explain cache hit/miss/forced-run decisions
pkf run --no-cache test        # bypass cache lookup AND store for this run
pkf run --refresh test         # bypass cache lookup but DO re-store (re-baseline)
pkf up dev                     # start every service:true task in dev's subgraph
pkf up --watch dev             # same, plus restart-on-change
pkf graph                      # emit Graphviz DOT for the full DAG
pkf graph --format mermaid     # emit Mermaid flowchart (renders on GitHub)
pkf graph --json               # machine-readable graph (tasks + edges)
pkf graph --target test        # only the subgraph rooted at `test`
pkf doctor                     # diagnose pkf PATH, pkl/cache/remote/taskfile setup
pkf doctor --json              # emit structured setup checks
pkf doctor --fix --dry-run     # preview replacing stale pkf on PATH with this binary
pkf format                     # pkl format -w on the Taskfile's directory
pkf format --check pkl examples # exit 11 (CI-friendly) if anything is unformatted
pkf hooks install              # write .git/hooks/<event> shims for matching tasks
pkf hooks list                 # show which hook events are wired
pkf affected --since=origin/main test  # run only tasks affected by the PR diff
pkf affected --files src/main.go --explain --dry-run  # inspect file -> task matches
pkf affected --check           # run workflowTests declared in Taskfile.pkl
pkf run a b c                  # run multiple targets in one go (topological union)
pkf run                        # no args = the `default` task (errors if absent)
pkf run -- a b c               # forward args to the `default` task when it accepts args
pkf run --timing build         # also print per-task wall time at the end
pkf run 'test:*'               # glob over task names (also works on affected / clean)
pkf clean                      # rm declared outputs of every task; --dry-run to preview
pkf cache stats                # local CAS: entries, size, oldest/newest
pkf cache prune --older-than=7d  # drop stale entries (--dry-run to preview)
pkf cache rm <action-key>      # remove a specific entry (≥2-char prefix accepted)
pkf cache clear --yes          # nuke everything (scripting-safe with --yes)
pkf run --quiet build          # suppress per-task log lines (errors + summary still print)
pkf completion bash > ~/.bash_completion.d/pkf  # dynamic task-name completion
pkf completion zsh > "${fpath[1]}/_pkf"
pkf completion fish > ~/.config/fish/completions/pkf.fish
pkf run --keep-going lint test # don't stop on first failure (Bazel / make -k)
pkf list --long                # audit task visibility/cache/quiet/deps/io/shell flags
pkf explain build              # dump every input to the action key (cache-miss debug)
pkf explain --diff old/Taskfile.pkl build  # compare action-key inputs against another Taskfile
pkf run --profile=ci build     # tag the run; $PKF_PROFILE + cache splits per profile
pkf run --on-fail=shell build  # drop into $SHELL in the failed task's workdir on error
pkf run --remote-only build    # skip local cache, only consult remote (verify remote populated)
pkf affected --watch           # re-evaluate affected set on every file change
pkf graph --target build --depth=1   # show only direct deps (one hop)
pkf graph --format tree        # terminal-readable dependency tree (roots only when no target)
pkf graph --format tree --target test --depth=2  # tree with deps up to two hops
pkf lint                       # detect dead local tasks, cache footguns, and suspicious task definitions
pkf lint --json                # emit machine-readable findings for CI/editor tooling
pkf lint --fix                 # safely add cache = false for outputs-without-inputs findings
pkf migrate --to=0.5.0         # rewrite Taskfile.pkl's amends URI + verify
pkf pkl-cache warm             # pre-populate ~/.pkl/cache (CI prefetch step)
pkf <plugin> <args>            # exec `pkf-<plugin>` on PATH (git-style fallthrough)

• PKF_TASK_NAME — the task's name.
• PKF_TASK_ROOT — absolute path to the task's workdir (or the Taskfile directory when workdir is null).
• PKF_WORKSPACE_ROOT — absolute path to the Taskfile's directory.

pkf graph | dot -Tsvg -o tasks.svg
pkf graph --format mermaid > tasks.mmd
pkf graph --format tree --target test

#Machine-readable introspection

{
  "tasks": [
    {
      "name": "build",
      "description": "Compile the app",
      "visibility": "public",
      "cmd": "moon build --target native --release",
      "deps": [],
      "inputs": ["src/**/*.mbt", "src/**/moon.pkg", "moon.mod"],
      "outputs": ["_build/native/release/build/main/main.exe"],
      "cache": true,
      "workdir": "services/api",
      "service": false,
      "services": [],
      "acceptsArgs": false,
      "inheritEnv": true
    }
  ]
}

{
  "tasks": [
    { "name": "build", "kind": "task", "deps": [], "cache": true },
    { "name": "ci", "kind": "aggregate", "deps": ["build"], "cache": true }
  ],
  "edges": [
    { "from": "build", "to": "ci" }
  ]
}

#Testing affected workflows

local build = new Task {
  name = "build"
  cmd = "moon build --target native --release"
  inputs { "src/**/*.mbt"; "moon.mod" }
  outputs { "_build/native/release/build/main/main.exe" }
}

local test = new Task {
  name = "test"
  cmd = "moon test"
  inputs { "src/**/*.mbt" }
  deps { build }
}

tasks { build; test }

workflowTests {
  new {
    name = "source edit rebuilds and retests"
    changed { "src/main.mbt" }
    direct { "build" }
    tasks { "build"; "test" }
  }
}

#Environment, args, and the action key

#Layer order (later wins)

1. host env (os.Environ())             ← inherited from the shell that ran pkf
2. defaults.Env                        ← Taskfile-wide common values
3. task.Env                            ← per-task overrides
4. resolved params (uppercased name)   ← `--bump=patch` → $BUMP

#Two contracts that are NOT the same

#When to use what

• You want cmd to see a host env var. Default state. Do nothing — inheritEnv = true already passes everything through.
• You want a host env var to also affect cache. Read it into task.Env explicitly:

  env { ["NODE_ENV"] = read("env:NODE_ENV") }

  Now cmd sees $NODE_ENV, AND a change to it invalidates the cache entry. The host env still flows through for everything else; this only promotes one value into the hashed layer.
• You want hermetic builds (release pipelines, reproducibility- sensitive CI). Set inheritEnv = false per task. cmd then sees only the tiny allowlist plus whatever you put in env { ... }, and the action key fully describes the env.
• You want runtime input that changes per invocation (a port, a bump kind, a watch flag). Declare params { ... }:

  params {
    new { name = "bump"; type = "enum"; choices { "patch"; "minor"; "major" }; default = "patch" }
    new { name = "port"; type = "int";  default = "3000" }
    new { name = "watch"; type = "bool"; default = "false" }
  }

  Callers pass pkf run task --bump=minor --port=8080 --watch; cmd reads $BUMP, $PORT, $WATCH. Different values cache as different entries — usually what you want.
• You want variadic positional args (the just *ARGS shape). Set acceptsArgs = true and write cmd = "node \"$@\"". Callers pass pkf run task -- a b c. The args fold into the action key, so command wrappers typically also set cache = false.
• You want helper tasks hidden from normal discovery. Set visibility = "internal". pkf list and pkf graph hide it by default, --all reveals it, and pkf run <name> can still execute it directly.

#Things that confuse agents

• read("env:X") is NOT how you read host env at runtime. It is Pkl-evaluation-time interpolation: the value at the time pkf evaluated the Taskfile gets baked into the rendered task. That is exactly what you want when you want the value to affect the action key, but if you only need cmd to see the var, plain inheritance is enough — don't write read("env:...") for ergonomics-only env like SSH_AUTH_SOCK.
• $VAR inside cmd is shell expansion, not Pkl interpolation. Write cmd = "echo $HOME" — pkfire passes the literal string to bash, bash expands $HOME from the merged env. Pkl's \(...) interpolation runs at schema evaluation time and bakes a constant into the rendered task — useful occasionally but rarely what you want for env vars.
• acceptsArgs = false is the default for a reason. A task that silently absorbs whatever comes after its name is a typo vector. Opt in only for command wrappers (script, test--grep=..., etc.).
• bool params do not consume the next token. --watch--port=80 parses as WATCH=true PORT=80. Use --watch=false for explicit negation. (int, string, enum do take the next token when written without =.)

#Pointing at the schema

#Remote cache

export PKFIRE_REMOTE_CACHE=https://pkfire-cache.<account>.workers.dev
export PKFIRE_REMOTE_TOKEN=<auth token>
pkf run build    # hits local first → falls back to remote → falls back to running

GET  /v1/cas/<hex64>   → 200 + tar.zst | 404
HEAD /v1/cas/<hex64>   → 200 | 404
PUT  /v1/cas/<hex64>   → 201 (or 200 if already present)
Authorization: Bearer <token>   (optional)

#Skill

#Used by

#Examples

#Status

#Development

moon build src/cmd/pkf --target native --release
BIN=_build/native/release/build/mizchi/pkf/src/cmd/pkf/pkf.exe

"$BIN" list                                      # see all maintenance tasks
"$BIN" run preflight                             # moon check/test + pkl-test + examples + version + format
"$BIN" run conformance                           # contract harness: candidate vs frozen goldens (43/43)
"$BIN" run fmt                                    # pkl format -w on Taskfile.pkl, pkl/, examples/, skills/
"$BIN" run fmt:check                             # formatting check without writing
"$BIN" run -f examples/dogfood/Taskfile.pkl ci   # full build + integration gate

# 1. Bump README + skills + recipes + PklProject. Examples are NOT
#    touched here — they pin to a *published* URL and would 404 on
#    `pkl eval` until the release workflow finishes.
pkf run bump --to=<new-version>
git commit -am "release: pkfire@<new-version>"

# 2. Tag locally and push. Release + v-tags workflows fire.
# The Release workflow extracts the body for the GitHub release page
# from CHANGELOG.md's `## [<new-version>]` section automatically —
# update that section BEFORE this step so the published notes match.
pkf run tag
git push origin main "pkfire@<new-version>"

# 3. After the publish workflow uploads the package, bump examples
#    in a follow-up commit.
perl -i -pe 's/pkfire\@<old>/pkfire\@<new-version>/g' \
  examples/basic/Taskfile.pkl examples/node/Taskfile.pkl \
  examples/rust/Taskfile.pkl examples/monorepo/Taskfile.pkl \
  examples/diagnostics/Taskfile.pkl examples/split-import/Taskfile.pkl \
  examples/split-import/tasks/*.pkl
git commit -am "examples: bump amends URI to pkfire@<new-version>"
git push

#License