CLI reference #

Every zap command, its flags, what it reads and writes, and its exit codes. For what the commands mean, see concepts.md; for a first run, see getting-started.md.

Every command that takes a config defaults it to ./zap.ts. zap with no command prints the loop and exits 0; zap --help prints the command list, and --help on any command prints its flags.

Commands at a glance

All of them but version evaluate the config first, with the fgro build zap.lock pins (zap lock pins the one it is given), and run the two machine-free gates: a hardcoded secret literal or a structural error (a duplicate id, a dangling depends_on, a cycle, service intent on a target with no service_manager, …) fails every command with the same message. See configs.md.

Shared flags

zap plan

Detects every declared resource live and renders the changeset: one [+] (create) or [~] (update) line per resource, its steps under it, and the plan_hash at the end. --diff adds per-resource current → desired attribute lines above a drifted resource's steps; every change still shows its steps, so the view prints everything the plan_hash covers, as zap plan does.

Under the header come the lines naming the machine and environment the plan is for. They are part of the plan and its hash, so a preview made as one user or under one HOME doesn't bind a wetrun as another: sudo zap apply --wetrun runs as root and refuses a review made without it.

Under each change come the lines that say what it declares (its name: when it has one, a file's path:, mode:, and content: descriptor, a link's to:, a script's check:, cwd:, and env:, an apt_repo's key: URL and the pin: its bytes must have, a swap's size:, a pipeline's max_concurrency: and its step: ids and step name: labels), then its steps. A content: descriptor's SHA-512 is of the text as written: for a template, the template before its variables are filled, followed on the same line by its vars and their kinds, each as JSON. Multi-line text prints indented under its first line, and control and invisible characters print as <U+XXXX> (security.md).

A step line starts with >, #, or =. > is a command Zap runs as written. # is never run as written: it is a verify assertion Zap checks itself, or a step the target's manager has no command for. = is one of Zap's own operations, named with what it acts on and never printed as the script that performs it:

• = put <path> installs a file (security.md). The parentheses give its mode, the account the write runs as, and a check the staged file must pass. Text Zap holds prints whole under text:, less its final newline, with its length and the start of its SHA-512; a text with no final newline says so in the parentheses. Text the target produces has a from: line saying where it comes from and what skips the put. Text the config supplies for it prints under line:: an apt source line (which the target's shell expands, at every plan as well as on apply, so a $VERSION_CODENAME in it is read there and a $(…) in it runs), an /etc/fstab entry.
• = run the script fetched from <url> (piped to <shell>) is an installer: the URL and the shell as the config declares them.
• = dir <path> creates a directory if it is missing and sets its mode and owner.
• = check <path> (not a link, below directories only root writes, as root) comes first in a swap file's creation, and refuses a link at the path or a directory on the way to it that another account can write (resources.md).
• = pg_hba rule: <line> adds the line to the server's pg_hba.conf, as the postgres account, unless it is already there. A line it adds is put in force by reloading the server's configuration; a line already there reloads nothing. A file that doesn't belong to postgres is left unchanged and the step fails, and so does a file the server can't parse (pg_hba_file_rules lists an error, checked before the reload), a reload it doesn't confirm, or a reload it doesn't load within 30 seconds.

A = step that fails is reported by the same words, in the run's report and in the change_failed event's error: put /etc/sudoers.d/deploy (mode 440, as root, checked by visudo) exited 93: ….

A pass that can't establish a verdict says so before the plan, under an UNDETERMINED, UNVERIFIABLE, or LOCK banner.

Exit codes:

The pass is recorded as a preview, so a following zap apply --wetrun binds to its plan (concepts.md). A plan whose host or connecting user resolves through a masked reference names no one machine: it is shown under an UNBINDABLE note with no plan_hash, and is not a preview. When it is the host, the pass also keeps no last-run report and says so under an UNRECORDED note.

zap apply

Without --wetrun, the same pass as plan, rendered as what apply would do, and exit codes that judge the result (below). It also resolves any missing tracked pin over the network and reports it as resolved, not yet written to zap.lock; the write waits for a wetrun.

--no-lock leaves the lock's entries alone: no tracked pin is read, nothing is fetched to pin a tracked source, and nothing is written. A tracked source then has no pin, so its resource holds; a config with none runs as usual, offline. The toolchain pin is still read, and without one the command refuses as any other does.

With --wetrun, apply:

1. rejects the run if any variable the config references is unset or empty, or if the target's host or connecting user resolves through a masked reference;
2. detects and plans;
3. checks the plan against the review (next section) and refuses if it doesn't match, or on an interactive terminal shows the plan and asks;
4. refuses if any planned command can't take a value its reference resolves to (a single quote in a command, for one), naming the resource and the variable; zap plan and a dry run warn about the same thing ahead of time;
5. claims the preview it bound to, so one preview covers one wetrun: of two wetruns started on one preview, the one that claims it first goes on and the other stops with nothing changed (exit 2);
6. re-checks that every reference the plan recorded still resolves to the recorded value, refusing (exit 2) if one moved while the run was in progress;
7. writes zap.lock when the config has tracked pins;
8. executes the changes in dependency order, stopping at the first failure, writing a pending-trigger marker on the target before the first source of a triggered service and clearing it after the service's change;
9. re-detects every resource and reports any that still isn't converged as RESIDUAL.

Binding to the review

A wetrun executes only the plan you reviewed: the plan it computes must equal, hash for hash, the one named by --expect-plan <hash> or the one in the most recent preview on this host. Otherwise it refuses, changes nothing, and exits 2. The rules are in concepts.md.

On an interactive terminal, a wetrun whose plan has no review (no preview, or a preview of a different plan) and no --expect-plan shows the plan and asks instead:

The plan and the question go to standard error; the report goes where it always does. The answer is the first eight characters of the plan's plan_hash, in either case. Input typed before the question appears is discarded, so neither a y nor an earlier run's answer typed ahead while Zap reads the machine runs anything. Those characters execute the plan shown and nothing else; any other answer (a y, the whole hash, an empty line, the end of the input) declines: the plan is rendered again under a DECLINED banner, recorded as the preview, and the exit is 2, as for a refusal. There is no flag that answers for you. Interrupting at the question (Ctrl-C) ends the run with nothing executed and nothing recorded as a preview, so the next wetrun asks again. It never asks under --json, for a mismatched --expect-plan, for a plan with no hash, or for a plan a command can't run.

Scripting. The question appears only on an interactive terminal, for a plan with no review. A script stays non-interactive by previewing first (a dry run, then the wetrun), by passing --expect-plan <hash>, or by running with standard input that isn't a terminal (< /dev/null). A non-interactive wetrun with no review of its plan refuses, and --json never asks.

--expect-plan makes the binding explicit: the hash from the plan you reviewed, perhaps in a pull request or an agent's transcript. The match is exact. A dry run rejects the flag. zap deploy follows the same rule against its own preview (below).

Exit codes:

zap deploy

Ships a release to a remote target: build locally, tarball the artifacts, upload, extract into releases/<version>, swap the current symlink, restart the service, poll health. Full mechanism: deploy.md.

A dry run reads zap.lock, connects over SSH to read the live current symlink, prints the plan (the resolved host, the declared target, the tree and preflight state, and every step with its command, script, paths, or URL), ends with the plan_hash, records the plan as this host's deploy preview, and exits 0. If the live release is already this version it reports server already at this version, prints no hash, records nothing, and exits 0, on a dry run too; --force deploys anyway.

A dry run prints no plan_hash and records no preview when:

• the host, connecting user, or health domain resolves through a masked reference;
• the checkout has uncommitted changes or untracked files and no --force (never reported as already at this version, since the tree isn't what the live release holds).

A wetrun of either is refused.

A wetrun executes only the reviewed plan, as zap apply's does, but against the deploy preview: its plan's hash must equal --expect-plan or the recorded preview's, or it refuses before the preflight and any step, becomes the new preview, and exits 2 (on an interactive terminal with no --expect-plan it asks for the start of the plan_hash instead). A wetrun that passes withdraws the preview before its first step, so one recorded preview covers one execution. zap status doesn't show the deploy preview. The rules are in deploy.md.

Flags:

--skip-build, --skip-preflight, --force on a dirty tree, and --bootstrap each change the plan, and so its hash: a wetrun binds to a preview made with the same flags.

Exit codes:

zap detect

The detection half of plan, rendered raw: one line per resource with its mark (ok, drift, absent, or ? for undetermined), its id and kind, and, for drift, what was observed. For validating that a probe reads a real target correctly. Over a host that resolves through a masked reference it keeps no last-run report and ends with an UNRECORDED note.

zap status

Offline: evaluates the config, reads the last-run report for the host the target resolves to (detection.md) and the on-disk zap.lock, and never touches the target. It says what the last run saw, never what the target is now; the live signal is zap plan. A referenced host needs its env (--env-file), as for a run. For an exact answer it needs the same env as the run that wrote the report, secrets included: a secret it can't mask reads as "config changed since", never as a false "unchanged".

Each line is a resource's verdict in that run, with a note when:

A preview's plan_hash is printed as the plan zap apply --wetrun binds to. The lock standing and an UNVERIFIABLE banner, for the last run or for now, lead the render. With no last run every resource is not read, so status exits 1 unless nothing is declared.

zap config validate

Evaluates the config and runs the two gates, nothing else. Prints ok: N resource(s) and exits 0, or the gate's message and exits 2. The fast check for CI and editors: no target, no network, no secrets needed, but a copy of the pinned fgro build (lock.md).

zap lock

The verbs over zap.lock, the ledger for the toolchain pin and the tracked remote files and build sources (lock.md).

zap lock pins the toolchain, the blake3 of the fgro binary it evaluates the config with, re-fetches every tracked source, re-mints every entry, drops orphans, and rewrites the file. All or nothing. It is the only command that evaluates with a binary the lock doesn't pin, and the only one that moves the toolchain pin (lock.md).

zap lock --check first holds the fgro binary to the toolchain pin: with a binary that hashes to something else it reports the pin stale without evaluating the config, so the entries go unchecked. Otherwise it classifies each entry offline as current, missing, stale (the resource changed since the pin), unverifiable (a variable the hash takes by value is unset), or orphaned. Its 1 is a read-only verdict, like plan's held resources; apply, which refuses to act on a stale or unverifiable entry, treats the same finding as an error and exits 2, as does a deploy wetrun's preflight.

Both print a note: for each reference the lock addresses by name only, because its name or the form of its value reads as a secret (lock.md).

zap update

Re-fetches the named resources, or every tracked one, and rewrites each entry whose pin advanced or whose recorded config hash is stale. Each advance is written as it happens, so a later failure keeps the earlier ones. A tracked URL that references an unset or empty variable is never fetched, and that entry fails. The config is --config <path> here, since the positional arguments are ids. A failed entry keeps the code its error has everywhere else: exit 1 if any failure is operational (a fetch, a write), else 2 if any entry failed on an input to fix (an unset reference in its URL or credential, a signature that doesn't verify). It prints the same note: lines as zap lock.

zap version

Prints zap <version>.

Banners

What a pass couldn't establish, or why it didn't act, leads its report:

Exit codes, all commands

The pattern across commands. The tables list 2 before 1 because 2 is still an established answer and 1 is not:

plan, detect, and a deploy dry run report rather than judge: pending changes exit 0 there.

An error prints as error: and its message; a message of several lines is indented under it, and any advice Zap adds follows at the left margin.

Errors raised before a report exists follow the same split.

Exit 2, a problem in your inputs:

• fgro: none named; a path that isn't absolute; one that is missing, a link, a script or set-ID file, or doesn't hash to the toolchain pin; one that answers in an eval protocol or graph version this zap doesn't read; no toolchain pin; an fgro pin cache under ~/.zap that isn't yours.
• zap.lock: one that doesn't parse or is newer than this zap reads; a lock stale or unverifiable; a content-hash or signature mismatch.
• The config: not found; named as its own lock would be (*.lock); it or its directory writable by every user; no project; a package.json on the way up that can't be read or isn't valid; no user the evaluation may run as (a project root owns, a project that is or holds that user's home, a directory on the way it can't search, a group or passwd entry it can't use); eval failure; a schema error.
• The environment: an env-file error; a ZAP_HOME or HOME unset where needed or not absolute; a state directory that isn't Zap's own; an unresolved reference on a wetrun.
• A wetrun refused before its first change: a plan that names no one machine, a command that can't take a value its reference resolves to, or a reference that moved while the run was in progress.
• A deploy wetrun from a checkout with uncommitted changes or untracked files and no --force.
• A usage error: an unknown flag, or --expect-plan without --wetrun.

Exit 1, a problem in the world: connectivity, a command that can't spawn, a file operation, a fetch, a git error; an fgro that crashed, wrote output that isn't its protocol, or couldn't be spawned; an fgro binary written while Zap hashed it or before it ran, which a retry clears once nothing writes it.

JSON events

--json on a wetrun of apply or deploy streams one JSON object per line to stdout, instead of the text report. A wetrun that ends before its first event (a refusal, a preflight bail, an already-deployed release) leaves stdout empty and prints its text report to stderr. Control and invisible characters in a value are written as JSON \u escapes, so the stream decodes to the same values and is safe to watch. Each event carries an event tag:

A step skipped after an earlier failure has no step_started, but a started step's outcome can be step_skipped too: a readiness check the target doesn't serve, or a rollback whose swap back finds nothing to do (another deploy holds the app's lock, current no longer names the failed release, or names nothing, or the previous release is gone). A rollback with nothing to return to is skipped without starting.

code on a failure is a triage category: transient, permission, not_found, conflict, permanent, or execution_failed (permission includes sudo's own refusals). A file operation Zap makes itself is classified by the error the system returned (a symbolic link or anything else in the way, or a full disk, is conflict; a timeout is transient); a command, or ssh, by its exit code and what it printed. Every value is masked: a resolved secret never appears in an event.

A run that streamed events doesn't print its text report, and the report's warning: lines go with it: the stream carries a warning only where an event holds it. A deploy's rollback is always one: rolled back, failed, or skipped, with nothing to return to (a broken release left live) among the skips. The others, such as a deploy's repairs of an unfinished one or a failed prune, aren't in the stream.

Environment variables Zap reads

Nothing that shapes a plan comes from Zap's own environment. Values a config needs come from references resolved from the operator environment or --env-file.