#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.16.0       # or @v0 to track the latest 0.x
      - run: pkf run ci

Why @v0.5.0 and not @pkfire@0.16.0? 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.16.0
      - 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.16.0#/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 --all                 # include internal tasks
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 --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 graph                      # dependency tree, one root per line
pkf graph --format dot         # Graphviz DOT (pipe to `dot -Tsvg`)
pkf graph --format mermaid     # Mermaid flowchart (renders on GitHub)
pkf graph --json               # machine-readable graph (tasks + edges)
pkf graph --target test        # only `test` and what it depends on
pkf graph --target test --depth=1  # one hop: direct dependencies only
pkf doctor                     # diagnose pkf PATH, pkl/cache/remote/taskfile setup
pkf doctor --json              # emit structured setup checks
pkf format                     # pkl format -w on the Taskfile's directory
pkf format --check pkl examples # exit non-zero (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 src/main.go       # list tasks affected by the given changed paths
pkf affected --changed=changed.txt     # read newline-separated changed paths from a file
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
pkf clean --dry-run            # list what would be removed, remove nothing
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 run -j 4 ci                # run up to 4 actions at once, respecting the graph
pkf run -j auto ci             # one per available CPU (capped at 16)
pkf run --sandbox test         # run against only the declared inputs
pkf explain build              # dump every input to the action key (cache-miss debug)
pkf run --profile=ci build     # tag the run; $PKF_PROFILE + cache splits per profile
pkf run --remote-only build    # skip local cache, only consult remote (verify remote populated)
pkf trace build                # list the workspace files the task actually read
pkf trace --check build        # fail when a file is read but no declared input covers it
pkf trace --emit build         # print an `inputs { ... }` block matching the observed reads
pkf lint                       # detect dead local tasks, cache footguns, and suspicious task definitions
pkf lint --json                # emit machine-readable findings for CI/editor tooling
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                                  # tree (default)
pkf graph --format dot | dot -Tsvg -o tasks.svg
pkf graph --format mermaid > tasks.mmd     # paste into a PR
pkf graph --json | jq '.edges'

flowchart LR
  gen["gen"]
  consume["consume"]
  gen -. "dist/out.txt" .-> consume

#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

#A task with no inputs is never cached

pkf: pre-push  will run (uncached: no declared inputs)  bb57cea3

#The action descriptor

mnemonic  executable  argv  env  inheritEnv
inputs (path + digest)  consumedArtifacts (path + digest)
outputs  workingDirectory
executionPlatform  executionProperties

#Evaluation is cached too

pkf list                    182 ms  ->    4 ms
pkf run fmt:check (cached)  190 ms  ->    7 ms

#What a run tells you it skipped

$ pkf run ci
pkf: $ build
pkf: $ test
pkf: 3 task(s) · 1 cached · 2 ran · 4.1s

$ pkf run ci                       # nothing changed
pkf: # build (cache hit 5a1b2c3d, replaying logs)
bundle: 412 kB
pkf: # test (cache hit 9e0f1a2b, replaying logs)
ok  47 passed
pkf: 3 task(s) · 3 cached · 0 ran · 12ms  (nothing to rebuild)

#Replayed logs

• A task that printed nothing says nothing extra — the hit line stays # name (cache hit 5a1b2c3d) rather than claiming a replay of an empty log.
• Each stream is capped at 1 MiB in the entry, with a line saying how much was dropped. Entries are downloaded whole on a remote hit, and an uncapped -v build would make that expensive for output nobody reads.
• Capturing means the command writes to a pipe rather than to the terminal, so tools that colour conditionally will turn colour off. This applies only to tasks that are actually cached; anything uncacheable — cache = false, no declared inputs, --no-cache — still gets the terminal directly. Output is not delayed either way: sequentially it is forwarded as it arrives.

#Running actions in parallel

• Output is buffered per action. Sequentially the command writes straight to your terminal, which is what makes a long build watchable. With several commands running at once those bytes would arrive shuffled, so each action's output is captured and printed as one block when it finishes — attributable, at the cost of arriving late.
• Ties break on the topological order. When several actions are ready, the one earliest in that order goes first. -j 1 is therefore identical to the old sequential walk, and any -j schedules the same way twice in a row.

pkf: task `build` failed with exit code 1
pkf: - test (skipped: `build` failed)
pkf: - ci (skipped: `build` failed)

pkf:   total  1.0s wall
pkf:   critical path  1.0s  compile -> link -> package

#Running an action against only what it declared

$ pkf run sneaky              # reads a file it never declared
pkf: $ sneaky
$ pkf run --sandbox sneaky
cat: undeclared/extra.txt: No such file or directory
pkf: task `sneaky` failed with exit code 1

pkf: task `messy` wrote `dist/scratch.log` without declaring it as an
     output (discarded; add it to `outputs` to keep it)

local check = new Task {
  name = "check"
  cmd = "cargo clippy -- -D warnings"
  inputs { "src/**"; "Cargo.toml"; "Cargo.lock" }
  hermetic = true
}

#Artifacts: the files are the edges

local build = new Task {
  name = "build"
  cmd = "esbuild src/app.ts --outfile=dist/app.js"
  inputs { "src/**" }
  outputs { "dist/app.js" }
}

local size = new Task {
  name = "size"
  cmd = "wc -c dist/app.js"
  inputs { "dist/app.js" }   // no `deps { build }` needed for ordering
}

• Order. In any run containing both, build is scheduled before size. pkf run size build runs them in that order regardless of how you listed them.
• Key soundness. The outputs of everything a task depends on are hashed into its action key as consumedArtifacts. Before this, a task that declared deps { build } but no matching inputs line had a key that could not see a single byte build wrote — so it stayed a cache hit while the thing it consumed changed underneath it.

task "size" reads "dist/app.js", which task "build" declares as output
"dist/app.js" (e.g. dist/app.js), but does not depend on it

#Timeouts

timeoutSeconds = 300

#Platform requirements

requiresPlatform { "linux/amd64"; "linux/arm64" }

pkf: task `build:deb` requires execution platform linux/amd64 or linux/arm64,
     but this machine is darwin/arm64

#Toolchains: resolved, not declared

local build = new Task {
  name = "build"
  cmd = "go build ./..."
  inputs { "**/*.go"; "go.mod" }
  outputs { "bin/app" }
  toolchains {
    new Toolchain { name = "go" }
    new Toolchain { name = "protoc"; versionCmd = "protoc --version" }
  }
}

toolchains (1):
  go  go version go1.26.2 darwin/arm64
    /opt/homebrew/bin/go

#Cross-compiling: what a task builds for

targetPlatform = "linux/arm64"

local ccTool = new Toolchain {
  name = "cc"
  forTarget {
    ["linux/arm64"] = "aarch64-linux-gnu-gcc"
    ["linux/amd64"] = "x86_64-linux-gnu-gcc"
  }
}

toolchains (1):
  cc -> aarch64-linux-gnu-gcc  aarch64-linux-gnu-gcc 13.2
    /usr/bin/aarch64-linux-gnu-gcc

#Steps: one task, several cached actions

local bundle = new Task {
  name = "bundle"
  steps {
    new Step {
      name = "codegen"
      cmd = "pnpm codegen"
      inputs { "schema/**" }
      outputs { "gen/**" }
    }
    new Step {
      name = "compile"
      cmd = "tsc -b"
      inputs { "src/**"; "gen/**" }
      outputs { "lib/**" }
    }
    new Step {
      name = "link"
      cmd = "esbuild lib/index.js --bundle --outfile=dist/app.js"
      inputs { "lib/**" }
      outputs { "dist/app.js" }
    }
  }
}

$ pkf run bundle
pkf: # bundle/codegen (cache hit 3f2063a2, replaying logs)
pkf: $ bundle/compile
pkf: $ bundle/link
pkf: 3 task(s) · 1 cached · 2 ran · 14ms

#Providers: what a dependency hands over

local cli = new Task {
  name = "cli"
  workdir = "crates/cli"
  cmd = "cargo build --release"
  inputs { "src/**"; "Cargo.toml" }
  outputs { "target/release/cli" }
  provides = new Providers {
    executable = "target/release/cli"
    env { ["CLI_CHANNEL"] = "stable" }
  }
}

local smoke = new Task {
  name = "smoke"
  workdir = "apps/web"
  cmd = "\"$PKF_CLI_EXECUTABLE\" --version"
  deps { cli }
}

• Direct dependents only. A provider does not travel a second hop. A variable appearing in a task that never named the producer is a surprise, not a convenience; a task that wants to pass something along declares it itself.
• The consumer wins a collision. Provider values sit between the module defaults.env and the task's own env, so a task's local declaration is never overridden by something it merely depends on.
• executable must be something the task produces. A path no outputs pattern covers is refused when the Taskfile loads, because the failure would otherwise surface in the dependent's command and be reported against the wrong task.

providers (2):
  PKF_CLI_EXECUTABLE=../../crates/cli/target/cli  (executable from `cli`)
  CLI_CHANNEL=stable  (env from `cli`)

#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 (44/44)
"$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