hammerkit

Execute

Run the tasks in your build file.

Running hammerkit without a command (or with the explicit run command) executes a task. It is the default command, so hammerkit build and hammerkit run build are equivalent.

Execute a task

Tasks can be executed by name.

hammerkit example

Pass arguments

Arguments after -- are appended to the task's last command, each quoted as one argument. The task then skips the cache, unless --cache <method> is given; its dependencies run without them, cached as usual.

hammerkit run test -- src/login.spec.ts -t "login flow"

A run that selects several tasks takes no arguments. See arguments.

Execute tasks with labels

Tasks can be executed by matching labels or filtered by label values.

By matching labels

-f type=build only executes tasks that have the given label value. Their dependencies don't need to match the label.

hammerkit -f type=build

By excluding labels

-e build=ios excludes tasks that have the given label value. A task without a matching label is excluded as well if any of its dependencies matches.

hammerkit -e build=ios

Options

Usage: hammerkit run [options] [task] [-- args...]

Options:
  -f, --filter <labels...>    filter task and services with labels
  -e, --exclude <labels...>   exclude task and services with labels
  -c, --concurrency <number>  parallel worker count (default: 4, unbounded when every task and
                              service requests cpus and memory)
  --skip-resource-check       start even when a task with its services requests more than
                              the host has
  -w, --watch                 watch tasks (default: false)
  --env <name>                environment
  -l, --log <mode>            log mode (choices: "interactive", "live", "grouped")
  --cache <method>            caching method to compare (choices: "checksum", "modify-date", "none")
  --no-summary                do not print the end-of-run summary
  --summary-json              emit the end-of-run summary as JSON (default: false)
  --explain                   print the cache-miss cause when a task rebuilds (default: false)
  --dry-run                   print the execution plan with predicted cache hits/misses without running (default: false)
  --cache-read-only           restore from cache backends but never push to them (or set HAMMERKIT_CACHE_READ_ONLY=1)
  --timeout <duration>        fail tasks without their own timeout after this long (e.g. 10m)
  --max-timeout <duration>    fail any task after this long, also one with a longer timeout
                              of its own (e.g. 2m)
  --network <level>           the most any task or service reaches besides its needs: none,
                              open or allow:<host>,<host>
  --no-skip-deps              run dependencies even when nothing needing them has to run
  --no-restore                only look cache hits up, download their outputs only when a
                              task that runs needs them
  -h, --help                  display help for command

--cache defaults to checksum everywhere — the same comparison runs locally and in CI, so a result cached on one is reused on the other. --log defaults to interactive outside CI and live in CI (hammerkit auto-detects CI from the CI, CONTINUOUS_INTEGRATION, BUILD_NUMBER or RUN_ID environment variables).

Build summary

After a run, hammerkit prints one line per task — executed or cached, and how long it took — followed by the totals and the cache hit ratio:

Summary:
  build    cached     0ms
  e2e      executed   4.5s
  install  cached     0ms
  1 executed, 2 cached (67% cache hit), 4.7s total

A dependency that wasn't needed because every task depending on it was a cache hit is listed as skipped — see dependencies of cached tasks.

--no-summary hides it; --summary-json prints it as JSON on stdout (and nothing else), for CI dashboards or agents. With --explain, every rebuilt task also prints why it missed the cache, and the summary gets a cause column.

Dry run

--dry-run prints the execution plan in order, with the predicted cache hit or miss (and its cause) for every task, without running anything:

hammerkit run e2e --dry-run
Dry run (no commands executed):
  1. install: cache miss (never cached)
  2. build: cache miss (source changed: src/app.js, dependency changed: install)
  3. e2e: cache miss (source changed: src/app.js, dependency changed: build)

See also explain and graph.

Checking without restoring

On a cache hit, hammerkit normally downloads the task's entry and restores its generates into the checkout, so the outputs are there afterwards. A CI check often only needs to know the task passed. With --no-restore, a hit is only looked up in the cache backend, and nothing is downloaded:

hammerkit run test --no-restore

Outputs are still restored where a run needs them: when a task that runs (a cache miss) or a service that starts depends on a hit, that hit's outputs are downloaded before it starts. A task that only groups others (no cmds) runs nothing, so it restores nothing either. --no-restore has no effect in watch mode.

Leave it off when a later step uses the outputs, for example a deploy after build, or a coverage upload after test. A hit leaves the checkout as it is, so outputs already on disk may be from an older state.

If an entry is removed from the cache before a task that needs it starts, the run fails. Run again without --no-restore.

Read-only cache

--cache-read-only (or HAMMERKIT_CACHE_READ_ONLY=1) restores results from cache backends but never writes to them — for untrusted runners such as agent sandboxes or pull requests from forks. See agents, workspaces and CI.

Stopping a run

Ctrl-C (SIGINT), a cancelled CI job or a supervisor stopping hammerkit (SIGTERM) and a closed terminal (SIGHUP) all stop a run the same way: running tasks are cancelled, their containers and the run's services are removed, and each local task's command gets SIGTERM for its whole process group. Whatever is still alive in that group after 10 seconds is killed; set HAMMERKIT_STOP_TIMEOUT_MS to change the grace period.

A container task's container is removed when the task ends, so docker ps shows nothing from hammerkit once a run is over. If hammerkit itself is killed (SIGKILL), clean removes what that run left behind.

On this page