hammerkit

CLI

All about the options that the hammerkit cli offers.

Usage: hammerkit [options] [command]

Options:
  -V, --version                  output the version number
  --verbose                      log debugging information (default: false)
  --file <path>                  set build file (default: .hammerkit.yaml)
  --set <NAME=value>             value for $NAME / ${NAME} references, ahead of
                                 the shell and .env (repeatable)
  -h, --help                     display help for command

Commands:
  ls [options]                   list all tasks
  clean [options]                clear cache and generated
  store [options] <directory>    save task outputs into <directory>
  restore [options] <directory>  restore task outputs from <directory>
  package [options] <registry>   package services into a docker image
  validate [options]             validate hammerkit configurations
  graph [options] [task]         serialize the build graph (tasks, services,
                                 deps/needs edges) as mermaid or dot
  explain [options] [task]       explain whether tasks would be a cache hit or
                                 miss, without running them
  includes                       manage remote includes (includes pull)
  cache                          inspect, prune and move cache entries
                                 (cache ls / prune / pull / push)
  up [options]                   start services(s)
  down [options]                 stop services(s)
  run [options] [task]           execute task (default command)
  help [command]                 display help for command

When no build file is present, only the init command is available, which creates a default .hammerkit.yaml. Point hammerkit at a non-default file with --file <path>.

--set NAME=value works with every command and in any position, as often as needed. It supplies the value of $NAME and ${NAME} references in the build file, ahead of the shell and .env files, so a run can be narrowed without exporting variables: hammerkit run e2e --set E2E_SPEC=e2e/login.cy.ts. Like any env value it is part of the cache key of the tasks that declare it.

Common options

These options are shared by the task-running commands (run, up) and, where they make sense, by clean, store, restore and validate:

OptionDefaultDescription
-f, --filter <labels...>–Keep only tasks/services matching key=value labels.
-e, --exclude <labels...>–Drop tasks/services matching key=value labels.
-c, --concurrency <number>4Number of tasks run in parallel. Unbounded by default when every task and service requests cpus and memory: the requests then bound the run.
--skip-resource-checkStart even when a task with the services it needs requests more than the host has.
-w, --watchfalseRe-run tasks when their src changes.
--env <name>–Run against a declared environment (e.g. a cluster).
-l, --log <mode>interactive (local) / live (CI)interactive, live or grouped.
--cache <method>checksumchecksum, modify-date or none. See caching.
--timeout <duration>–Default timeout for tasks without their own.
--max-timeout <duration>–Timeout for every task, also one with a longer timeout of its own: each task runs at most the shorter of the two.
--network <level>–The most any task or service of the run reaches besides its needs: none, open or allow:<host>,<host> (a host may carry a port for a TCP forward), whatever it declares. Fails with a local task in the run.

Label filters are always key=value; a key-only -f dev is rejected.

Parallelism

Independent tasks and dependencies run concurrently up to --concurrency workers (default 4). A task only starts once all of its deps have completed and all of its needs are healthy; tasks on separate branches of the graph run at the same time. If any task fails, or a service a task needs fails to start, hammerkit stops scheduling new work and the run fails.

When more tasks are ready than there are free workers, the one on the longest remaining chain starts first: the one whose own duration plus that of the longest line of tasks waiting for it is the largest. See which ready task runs first.

Exit codes

CodeMeaning
0Everything requested succeeded (including a fully cached run).
1A task, service, or command failed (build error, validation error, store/restore/package/clean/up/down failure).
127The requested task was not found.

These make hammerkit safe to chain in CI with && or as a pipeline step.

CI detection

Hammerkit auto-detects CI from the CI, CONTINUOUS_INTEGRATION, BUILD_NUMBER or RUN_ID environment variables. The only thing this changes is the default log mode (live in CI, interactive otherwise). The cache method default is checksum everywhere, so a result cached locally is reused in CI and vice versa.

On this page