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 commandWhen 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:
| Option | Default | Description |
|---|---|---|
-f, --filter <labels...> | – | Keep only tasks/services matching key=value labels. |
-e, --exclude <labels...> | – | Drop tasks/services matching key=value labels. |
-c, --concurrency <number> | 4 | Number 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-check | Start even when a task with the services it needs requests more than the host has. | |
-w, --watch | false | Re-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> | checksum | checksum, 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
| Code | Meaning |
|---|---|
0 | Everything requested succeeded (including a fully cached run). |
1 | A task, service, or command failed (build error, validation error, store/restore/package/clean/up/down failure). |
127 | The 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.