Every command, its flags, the global flags, the environment overrides, and the exit codes. Gatekeeper 0.3.0.
ReferenceFor developers
gatekeeper [command] [flags]
Every command takes --json where it prints a report. Every command exits with a meaningful status.
Exit codes
Exit
Meaning
0
fine
1
something went wrong
2
you typed it wrong
3
verified, but not admitted (verify, endpoint trust add --from-upstream, policy test)
4
the configuration is missing, invalid or unfinished
69
the capability is not wired into this build
Global flags
Flag
Meaning
-c, --config string
path to config.yaml; outranks every other layer. Unset, the file is resolved from $CR_GATEKEEPER_CONFIG, then $GATEKEEPER_CONFIG, then the per-system default on Gatekeeper configuration file. The flag’s own help text names only the first of those three
--fail-mode string
behaviour without a valid verdict: closed or open
--initial-timeout string
how long the first request waits for a verdict, for example 15s
--log-format string
text or json
--log-level string
debug, info, warn, error
--max-bundle-age string
reject bundles older than this, for example 24h
--metrics-listen string
host:port for the Prometheus endpoint
--reattest-interval string
background re-verification period, for example 5m
--verdict-cache-ttl string
how long an on-demand re-check reuses a verdict, for example 60s
Precedence, weakest first: built-in defaults, the file, CR_GATEKEEPER_* environment variables, command-line flags. Every tuning knob has an environment form, globally (CR_GATEKEEPER_REATTEST_INTERVAL) or per endpoint (CR_GATEKEEPER_ENDPOINT_<NAME>_FAIL_MODE).
init
Writes a commented configuration skeleton at the resolved config path. The file is deliberately not runnable: no trusted roots and no endpoints, because there is no trust-on-first-use.
Flag
Meaning
--force
overwrite an existing configuration file
--json
print the result as JSON
endpoint
Manages the proxied endpoints and their pinned evidence.
Appends a local listener for one upstream. Written without pins unless --trust is given; until the endpoint has a pin it can never admit traffic.
Flag
Meaning
--listen host:port
local address to bind, for example 127.0.0.1:8443
--upstream https://host
the router endpoint's origin
--trust stringArray
pinned evidence digest; repeatable; accepts sha256:<hex>, sha256/<base64url> or bare hex
--fail-mode closed
closed or open for this endpoint; omit to inherit the global default
endpoint discover <endpoint|hostname>
Verifies an endpoint and prints its evidence (chain, matched root, fingerprints, evidence digest, container images) so a deployment can be reviewed before pinning. Never writes to the configuration. Takes a configured name or a bare hostname. --json.
endpoint list
Lists the configured endpoints.
endpoint rm <name>
Removes an endpoint and its pins.
endpoint trust add <endpoint> [digest]
Pins a digest you supply, or with --from-upstream the one the endpoint publishes right now, after verifying it and printing the report. A bundle that fails any stage is never pinned.
Flag
Meaning
--from-upstream
pin the digest the endpoint publishes right now, after review
-y, --yes
do not ask for confirmation
endpoint trust list <endpoint>
Lists an endpoint's pinned digests.
endpoint trust rm <endpoint> <digest>
Unpins a digest.
trust
Manages the global trust anchors.
trust roots add <name> --pem-file <file>
Reads a PEM certificate and records it under a name; - reads standard input. Roots are identified by fingerprint, so adding one already trusted under another name is a no-op. Replacing one is rm then add.
trust roots list, trust roots rm <name>
trust measurements add [measurement]
Pins a measurement you supply, or with --from-upstream <endpoint|hostname> the one the root certificate of a live endpoint attests to, after running the whole attested-root check and printing the hardware report. A report whose signature does not verify, or whose reportData does not commit to the certificate's key, is never pinned.
Flag
Meaning
--from-upstream string
pin the measurement this endpoint's root attests to right now, after review
Runs the whole pipeline once against a live host and evaluates every policy. Exit 0 when the endpoint would be admitted, 3 when it would not. A hostname that is not configured has no pins, so it can be verified but never admitted.
Flag
Meaning
--endpoint string
evaluate against this endpoint's pins when the argument is a bare hostname
--json
print the result as JSON
run
Starts every configured endpoint and keeps them attested. With a terminal it opens the dashboard; --headless streams log lines. SIGHUP reloads in place; SIGINT and SIGTERM drain and exit.
Flag
Meaning
--headless
log to stdout instead of opening the dashboard
--drain-timeout duration
how long a graceful shutdown waits for in-flight requests (default 30s)
--demo
drive the dashboard from invented data; nothing is fetched or verified
status
Asks the running Gatekeeper, through its admin socket, for the state of every endpoint. It reports; it does not verify. Exit 69 when no admin: section is configured.
Flag
Meaning
--endpoint string
show the full report for one endpoint
--json
print the result as JSON
policy
policy list
Lists the policy packages that would be evaluated.
policy test <bundle.json>
Evaluates your policies offline against a saved bundle. The run is policy-only unless the build has an attestation pipeline wired in: signature, chain, freshness and the live channel are not checked, and every shortcut is listed. Exit follows the policy decision, 0 for allow, 3 for deny.
Flag
Meaning
--endpoint string
evaluate as this endpoint; default: the one whose upstream matches the bundle
--show-input
also print the exact input document the policies saw
--json
print the result as JSON
config
config path
Prints the configuration file this invocation would use, and which of the four layers chose it: --config, $CR_GATEKEEPER_CONFIG, $GATEKEEPER_CONFIG or default. This is the reliable way to name the file on a machine you do not know, because the default differs per operating system.
config validate
Applies the same rules startup does and lists every problem, each addressed by its path in the document. Exit 0 when ready to run, 4 when not. --json.
version
Prints the build identity:
terminal
$ gatekeeperversiongatekeeper 0.3.0 (commit f23d2d6ef30c27785028b6dfc7f3d2f9a86a60a5, built 2026-10-09T11:19:08Z, go1.26.0, linux/amd64)