Ctrlk
HomeGuardrailsIntegrationsBlogAutomate Now ◉Get a Demo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Lunar CLI Reference

Complete reference for every Lunar CLI command, subcommand, flag, and environment variable across collectors, catalogers, policies, and Hub operations.

This document provides a comprehensive reference for all available options and commands in the Lunar CLI.

Global options

--config-dir <config-dir>, LUNAR_CONFIG_DIR=<config-dir>

  • Type: string

  • Optional

  • Default: .

The path to the directory containing lunar-config.yml. This path is relative to the current working directory.

--hub-host <hostname>, LUNAR_HUB_HOST=<hostname>

  • Type: string

  • Optional

Override the URL of the Lunar Hub host name. This setting is inferred from the Lunar config if not specified.

--hub-grpc-port <port>, LUNAR_HUB_GRPC_PORT=<port>

  • Type: integer

  • Optional

Override the GRPC port of the Lunar Hub. This setting is inferred from the Lunar config if not specified.

--hub-http-port <port>, LUNAR_HUB_HTTP_PORT=<port>

  • Type: integer

  • Optional

Override the HTTP port of the Lunar Hub. This setting is inferred from the Lunar config if not specified.

--hub-insecure, LUNAR_HUB_INSECURE=true

  • Type: boolean

  • Optional

If true, use insecure HTTP connections to the Hub server.

--no-hub, LUNAR_NO_HUB=true

  • Type: boolean

  • Optional

Skip Hub interactions for dev commands (lunar collector dev and lunar policy dev). When enabled, the commands will run without connecting to Lunar Hub. Note that --component-json is required for lunar policy dev when this option is enabled, and LUNAR_GITHUB_TOKEN (or LUNAR_GITLAB_TOKEN, for components on GitLab) must be set if GitHub or GitLab access is needed.

LUNAR_HUB_TOKEN

  • Type: string

  • Required for commands that interact with the Hub server

The Lunar Hub token to use for authentication.

Licence Commands

Inspect a Lunar licence JWT and extract artefacts for cluster bootstrap. These commands run locally — they verify the licence against a trust list embedded in the lunar binary, so they work before a Hub exists (the canonical bootstrap case).

Shared options

--licence-file <path>, LUNAR_LICENCE_FILE=<path>

  • Type: string

  • Required (or set the env var)

Path to the licence JWT on disk. All lunar licence subcommands accept this flag, or read LUNAR_LICENCE_FILE if it's unset.

lunar licence verify

  • Form:

Verify the licence signature against the trust list embedded in this binary and print a customer-facing summary: tenant, expiry, and whether the licence carries a GHCR image-pull credential. Credentials are never printed — use lunar licence registry-token if you need the credential itself for manual docker login.

Example output:

lunar licence pull-secret

  • Form:

Emit a Kubernetes imagePullSecret (type kubernetes.io/dockerconfigjson) that authenticates the cluster against ghcr.io using the credential carried in the licence. Pipe to kubectl apply -f -, commit to GitOps, whatever fits.

Errors if the licence does not carry a GHCR pull credential.

--namespace <ns> | -n

  • Type: string

  • Required

Kubernetes namespace for the Secret.

--name <name>

  • Type: string

  • Optional

  • Default: regcred

Kubernetes Secret name. The Hub chart's imagePullSecrets reference defaults to regcred.

--out <path> | -o

  • Type: string

  • Optional

Write the manifest to a file instead of stdout. The file is created with mode 0600 because it contains a sensitive credential.

Examples

lunar licence registry-token

  • Form:

Print the raw GHCR pull credential from the licence to stdout, suitable for piping into docker login --password-stdin. Errors if the licence does not carry one.

Example:

Config Commands

lunar config schema

  • Form:

Print the JSON Schema (draft-07 format) for lunar-config.yml to stdout, generated from the same manifest definition the Hub uses. Redirect it into your config repo for editor autocomplete and inline structural feedback:

The schema is a structural aid only (it can't resolve uses: plugins). For authoritative pre-merge validation, use lunar hub pull --dry-run. See Validating your config.

lunar hub pull

  • Form:

The lunar hub pull command is used to instruct Lunar Hub to pull the latest configuration from a given repository.

For GitHub Actions workflows, the sync-config action is a thin wrapper around this command and exposes the same flags as inputs.

Using --rerun-code-collectors or --rerun-catalogers can trigger a large amount of work in Lunar Hub, especially across many components or PRs. Expect a backlog and elevated load while the reruns process.

<repo>

  • Type: string

  • Form: github://<owner>/<repo>@<branch-or-sha> or gitlab://<host>/<namespace>/<project>@<branch-or-sha>

  • Required

The repository to pull configuration from. This should be the main repository containing your lunar configuration files.

Examples:

  • github://acme-corp/lunar@main

  • github://acme-corp/lunar@de4adbeef

  • gitlab://gitlab.com/acme-corp/lunar@main

  • gitlab://gitlab.example.com/acme-corp/platform/lunar@main

The GitLab form requires an explicit host, including for gitlab.com, and the namespace may contain subgroups.

--dry-run

  • Type: boolean

  • Optional

Validate the configuration and exit without applying it. The dry run performs the Hub's own load-and-validate steps against the same code — clone the config, load lunar-config.yml + lunar-config.d/ fragments, resolve every uses: plugin, validate the whole manifest, and resolve each unpinned component's default branch — then stops before persisting. It does not install per-snippet dependencies, so that one step could still fail on a real pull; see Validating your config for the details.

It needs no Hub connection, which makes it suitable as a pre-merge CI check. It does need GitHub or GitLab access to resolve uses: plugins (set LUNAR_GITHUB_TOKEN or LUNAR_GITLAB_TOKEN, or configure the Hub as an auth source). Exits non-zero on any validation error. See Validating your config for a CI example.

--rerun-code-collectors | -l

  • Type: boolean

  • Optional

Rerun affected code collectors after applying the configuration.

--include-pr-commits

  • Type: boolean

  • Optional

Include PR commits when rerunning code collectors.

--pr-max-age-days <days>

  • Type: integer

  • Optional

  • Default: 5

Ignore PR commits older than this maximum number of days.

--rerun-catalogers | -t

  • Type: boolean

  • Optional

  • Default: false

Rerun global catalogers after pulling the manifest. Catalogers are skipped by default — pulling a manifest no longer triggers them automatically. Per-component catalogers (component-repo, component-cron) are unaffected and continue to run on their own hooks.

lunar hub run-code-collectors

Deprecated — use lunar collector run. That command covers cron collectors as well, and can scope a rerun to one component, PR, or commit. lunar collector run --only-code is the closest equivalent.

This command still works and is not scheduled for removal. It remains the only collector trigger available against a Lunar Hub older than the release that added lunar collector run, and it is currently the only way to sweep primary-branch commits without also covering recent PR commits.

  • Form:

The lunar hub run-code-collectors command instructs Lunar Hub to rerun code collectors.

This command can trigger a large amount of work in Lunar Hub. It reruns code collectors across all components — and across recent PR commits when --include-pr-commits is set — which can produce a significant backlog and elevated load.

--pr-max-age-days <days>

  • Type: integer

  • Optional

  • Default: 5

Ignore PR commits older than this maximum number of days.

--include-pr-commits

  • Type: boolean

  • Optional

Include PR commits when running code collectors.

lunar hub get-logs

  • Form:

The lunar hub get-logs command retrieves logs from Lunar Hub.

--namespace <namespace> | -n

  • Type: string

  • Optional

The Kubernetes namespace to retrieve logs from.

--output <format> | -o

  • Type: string

  • Optional

Output format for the logs.

--tail <lines>

  • Type: integer

  • Optional

Number of lines to show from the end of the logs.

Domain Commands

lunar domain ls

Coming Soon — This feature is not yet available.

  • Form:

The lunar domain ls command is used to list all domains.

Component Commands

lunar component ls

Coming Soon — This feature is not yet available.

  • Form:

The lunar component ls command is used to list all components.

lunar component get-json

  • Form:

The lunar component get-json command is used to retrieve the component JSON for a specified component.

[component-name]

  • Type: string

The name of the component to retrieve the JSON for. If not provided, falls back to the LUNAR_COMPONENT_ID environment variable.

--git-sha <git-sha>

  • Type: string

  • Optional

The specific git SHA to retrieve the component JSON for. If not specified, the latest component JSON will be retrieved.

--pr <pr-number>

  • Type: integer

  • Optional

The PR number to retrieve the component JSON for. If not specified, and no git SHA is provided, the component JSON for the primary branch will be retrieved. Combined with --git-sha, it narrows the lookup to that commit as seen in that PR; a --git-sha on its own resolves the commit whether it was reached through the primary branch or a PR.

--pretty | -p

  • Type: boolean

  • Optional

Pretty-print the JSON output.

Example:

Cataloger Commands

lunar cataloger manages catalogers from outside. This is distinct from lunar catalog, which is the SDK command catalogers use inside their own scripts to emit catalog entries.

lunar cataloger get-json

  • Form:

The lunar cataloger get-json command retrieves the catalog JSON from Lunar Hub. By default it returns the latest merged catalog snapshot (the same JSON that all catalogers contribute to). Use --cataloger to fetch a single cataloger's most recent contribution (its delta), --component to scope a per-component cataloger to one component, and --ts to fetch a historical snapshot.

--cataloger <name>

  • Type: string

  • Optional

Name of the cataloger whose delta should be returned. If omitted, the merged catalog snapshot is returned. The cataloger is resolved by exact name in the current manifest; an unknown name returns an error.

Whether --component is allowed depends on the cataloger's hooks:

  • A global cataloger (only cron / repo hooks) returns a single delta. Passing --component is rejected.

  • A per-component cataloger (any component-cron / component-repo hook) stores one delta per component. --component is required; omitting it is rejected with a "per-component scoped" error.

--component <name>

  • Type: string

  • Optional

Component to scope the lookup to (e.g. github.com/my-org/my-repo). Only valid together with --cataloger, and only for per-component catalogers — required for those, rejected for purely global ones. Returns the delta that cataloger emitted for the named component.

--ts <timestamp>

  • Type: string

  • Optional

Return the row whose created_at is at or immediately before this timestamp. If omitted, the latest row is returned. The command exits with an error if no row exists at or before the timestamp.

Accepted formats (parsed in this order):

  • Date only: 2026-05-01 (interpreted as 2026-05-01T00:00:00Z)

  • Date + time without timezone: 2026-05-01T12:34:56 (interpreted as UTC)

  • Full RFC3339: 2026-05-01T12:34:56Z or 2026-05-01T12:34:56-07:00

--pretty | -p

  • Type: boolean

  • Optional

Pretty-print the JSON output.

Examples:

lunar cataloger run

  • Form:

The lunar cataloger run command triggers cataloger execution in Lunar Hub. The CLI enqueues the matching catalogers, then polls every 10 seconds and prints queued / success / error counters until every job is in a terminal state. With no flags, it runs every cataloger in the current manifest. Use --cataloger and/or --component to narrow the scope.

--cataloger <name>

  • Type: string

  • Optional

Run only the named cataloger (exact match or dotted-plugin prefix like myplugin). If omitted, every cataloger in the manifest participates. When the named cataloger has only global hooks, combining it with --component is rejected. When the named cataloger has per-component hooks and --component is omitted, it fans out to every component in the manifest.

--component <name>

  • Type: string

  • Optional

Scope per-component hooks (component-repo / component-cron) to this single component. When omitted, those hooks fan out across every component in the manifest. Global hooks (cron / repo) are unaffected.

--output-json

  • Type: boolean

  • Optional

After the polling loop completes, fetch and print the merged catalog JSON. If no catalog row exists yet (fresh manifest with no completed catalogers), prints (no catalog yet) to stderr and exits with the same code as if --output-json were not set.

Failures: for any job that ends in the error bucket, the CLI prints a one-line summary including a deep link to the Grafana run-details dashboard (if Hub is configured with HUB_GRAFANA_URL_BASE). When no snippet_run is found for a job (rare — worker crashed before recording the run), the link is replaced with (no run record; check hub logs).

Example:

lunar cataloger dev

  • Form:

Catalogers can be highly environment-dependent. Be mindful of "works on my machine" types of issues.

The lunar cataloger dev command runs catalogers locally on the user's machine without applying changes to the catalog. It mirrors lunar collector dev for catalogers: the cataloger snippet is fetched from the configured manifest, executed under the configured runtime (Python / Node / Bash, or Docker when the snippet has an image), and its output is printed. No data is written to Lunar Hub.

[cataloger-name]

  • Type: string

  • Optional

Cataloger name (or dotted plugin name like myplugin.sync) to execute. If omitted, every cataloger applicable to the resolved scope is run.

--component <name>

  • Type: string

  • Optional

Look the component up in the resolved manifest. Required when running a per-component cataloger. Mutually exclusive with --component-dir.

--component-dir <path>

  • Type: string

  • Optional

Treat the given local directory as the component checkout (no clone). Mutually exclusive with --component and --config.

--config <repo>

  • Type: string

  • Optional

Remote configuration repository to load the manifest from (e.g. github.com/org/repo or github://org/repo@branch). Mutually exclusive with --component-dir.

--git-sha <sha>

  • Type: string

  • Optional

Pin the component checkout to this SHA on the component's primary branch. Only meaningful for per-component catalogers. Defaults to the tip of the primary branch.

Unlike lunar collector dev, there is no --pr flag — catalogers run on pushes to main, not on PR commits.

--script <path>

  • Type: string

  • Optional

Override the cataloger's main script with a local file path. Combine with --script-lang to control the runtime used.

--script-lang <language>

  • Type: string

  • Optional

  • Default: bash

Language for --script (bash / python / node).

--use-system-runtime

  • Type: boolean

  • Optional

Use the host's system Python / Node / Bash instead of the bundled Lunar runtimes. Defaults to true on non-Linux-amd64 hosts.

--no-cache

  • Type: boolean

  • Optional

Delete cacheable temporary files before running. Use this to force a clean run when troubleshooting.

--verbose

  • Type: boolean

  • Optional

Stream the cataloger's engine stdout / stderr to the terminal as it runs.

--secrets <k=v,k=v>

  • Type: string

  • Optional

Supplemental secrets injected into the cataloger's environment, parsed as comma-separated key=value pairs.

--output-json

  • Type: boolean

  • Optional

Print the merged Catalog JSON the user would see if these catalogers ran in Hub (manifest base + cataloger deltas + manifest overrides), in the same shape as Catalog JSON. Without this flag, each cataloger's raw emitted JSON is printed under a per-cataloger header.

Example:

Collector Commands

lunar collector run

  • Form:

The lunar collector run command is used to rerun code and cron collectors for a given component. This command triggers execution in the cloud via Lunar Hub.

Collectors are dispatched asynchronously, so the command reports what it triggered rather than waiting for results. Read the outcome with lunar component get-json once the collectors have run.

Naming a collector that isn't in the current manifest is an error. Lunar Hub checks the names given to --collector before dispatching anything, so a typo fails the command instead of quietly running nothing.

<component-name>

  • Type: string

  • Optional

The name of the component to rerun collectors for. Omit it to cover every component, across both code and cron collectors. The code leg also covers recent PR commits, bounded by --pr-max-age-days.

Omitting the component name can trigger a large amount of work in Lunar Hub. It reruns collectors across every component, which can produce a significant backlog and elevated load.

Naming a component is the only way to bound both legs. --pr-max-age-days bounds the code leg alone: the cron leg fans out over every open pull request of every component it matches, capped per component rather than by age.

--pr <pr-number>

  • Type: integer

  • Optional

The PR number to rerun collectors for. If not specified, collectors will be run for the component's primary branch. Requires a component name, since the PR is resolved against that component's repository.

--git-sha <git-sha>

  • Type: string

  • Optional

The specific git SHA to rerun collectors for. If specified, this takes precedence over --pr. Requires a component name, and the commit must be one Lunar Hub has already ingested for that component's repository.

--only-code

Run only code collectors.

--only-cron

Run only cron collectors.

--collector <collector-name>

  • Type: string

  • Optional

  • Repeatable

Run only the specified collector. This flag can be repeated to run multiple specific collectors. A name matches a collector exactly, or matches every sub-collector of a plugin: --collector trivy selects trivy.auto and trivy.rescan.

--pr-max-age-days <days>

  • Type: integer

  • Optional

  • Default: 5

Ignore PR commits older than this maximum number of days. Only consulted for the fleet-wide code sweep, which covers recent PR commits as well as each repository's primary branch. Cron collectors ignore it, so it has no effect at all under --only-cron.

--output-json

Output the results in JSON format: one object per triggered run, carrying component, collector, source (code or cron), repo_uri, commit_sha, and pr. A run that Lunar Hub deduplicated onto an identical run already in flight is reported with already_pending: true rather than omitted, so an empty array means nothing matched.

Example:

lunar collector dev

  • Name Form:

  • Script Form:

Collectors can be highly environment-dependent. Be mindful of "works on my machine" types of issues.

The lunar collector dev command is used to run a collector for a given component in development mode without applying changes. This command executes locally on the user's machine and outputs the resulting component JSON.

<collector-name>

  • Type: string

  • Required in Name Form

--script <path-to-collector-script>

  • Type: string

  • Required in Script Form

--component <component-name>

  • Type: string

The name of the component to run collectors for. If not provided, falls back to the LUNAR_COMPONENT_ID environment variable. Mutually exclusive with --component-dir.

--component-dir <path>

  • Type: string

Local directory containing the component to run collectors for. The directory must be a git repository. The component name is derived from the git remote URL. Mutually exclusive with --component.

--pr <pr-number>

  • Type: integer

  • Optional

The PR number to run collectors for. If not specified, collectors will be run for the component's primary branch.

--pr requires a GitHub connection and is not available for components on GitLab — the command exits with an error. Use --git-sha, or the component's branch, instead.

--git-sha <git-sha>

  • Type: string

  • Optional

The specific git SHA to run collectors for. If specified, this takes precedence over --pr.

<collector-name>

  • Type: string

  • Optional

The name of the collector to run. If not specified, all collectors will be run.

The path to a bash collector script file to run in development mode.

--fake-ci-cmd <bash-command>

  • Type: string

  • Optional

A command that the CI would have executed, that would cause lunar instrumentation to trigger an event for. This command is not actually executed, it is merely used to test collector triggering logic (e.g. would the collector trigger regex match the command line). This option is used for testing CI collectors locally without requiring an actual CI pipeline execution.

--config <repo>

  • Type: string

  • Optional

Remote config repository to use.

--use-system-runtime

  • Type: boolean

  • Optional

Use the system runtime instead of a containerized environment.

--no-cache

  • Type: boolean

  • Optional

Disable caching.

--verbose

  • Type: boolean

  • Optional

Enable verbose output.

--merge

  • Type: boolean

  • Optional

Merge the collected data into the existing component JSON.

--secrets

  • Type: boolean

  • Optional

Fetch and inject secrets into the collector execution environment.

Examples

Credentials

What credentials lunar collector dev needs depends on how you name the component:

  • --component-dir <path> runs against a checkout you already have. It performs only local git operations (no clone), so it needs no Hub and no GitHub or GitLab token. This is the way to smoke-test a collector against a local component with no credentials — pair it with --no-hub to skip Hub entirely, and --script to run a single script without resolving the manifest.

  • --component <name> must resolve the component's default branch and clone it, so it needs either a configured Hub or a token — LUNAR_GITHUB_TOKEN, or LUNAR_GITLAB_TOKEN for a component on GitLab. Without one, the command errors and points you at --component-dir.

Policy Commands

lunar policy ls

Coming Soon — This feature is not yet available.

  • Form:

The lunar policy ls command is used to list all policies.

lunar policy check ls

Coming Soon — This feature is not yet available.

  • Form:

The lunar policy check ls command is used to list all checks.

lunar policy run

Coming Soon — This feature is not yet available.

  • Form:

The lunar policy run command is used to rerun all policies for a given component. This command triggers execution in the cloud via Lunar Hub.

<component-name>

  • Type: string

The name of the component to rerun policies for.

--pr <pr-number>

  • Type: integer

  • Optional

The PR number to rerun policies for. If not specified, policies will be run for the component's primary branch.

--git-sha <git-sha>

  • Type: string

  • Optional

The specific git SHA to rerun policies for. If specified, this takes precedence over --pr.

--policy <policy-name>

  • Type: string

  • Optional

  • Repeatable

Run only the specified policy. This flag can be repeated to run multiple specific policies.

--initiative <initiative-name>

  • Type: string

  • Optional

  • Repeatable

Run only policies under the specified initiative. This flag can be repeated to run policies under multiple initiatives.

--output-json

Output the results in JSON format.

Example:

lunar policy dev

  • Name Form:

  • Script Form:

Policies can be highly environment-dependent. Be mindful of "works on my machine" types of issues.

The lunar policy dev command is used to run a policy against a component for local testing purposes. This command executes locally on the user's machine and outputs the check results in JSON format.

<policy-name>

  • Type: string

  • Required in Name Form

--script <path-to-policy-script>

  • Type: string

  • Required in Script Form

--component <component-name>

  • Type: string

The name of the component to run the policy against. If not provided, falls back to the LUNAR_COMPONENT_ID environment variable.

--component-json <path-to-json-or-stdin>

  • Type: string

The path to the component JSON file or - to read from stdin.

--pr <pr-number>

  • Type: integer

  • Optional

The PR number to run the policy against. If not specified, the policy will be run against the component's primary branch.

--git-sha <git-sha>

  • Type: string

  • Optional

The specific git SHA to run the policy against. If specified, this takes precedence over --pr.

--with <args>

  • Type: string

  • Optional

Arguments passed to the policy script.

--script-lang <language>

  • Type: string

  • Optional

  • Default: python

The script programming language.

--output <format>

  • Type: string

  • Optional

  • Values: json, list

Output format for the policy results.

--config <repo>

  • Type: string

  • Optional

Remote config repository to use.

--use-system-runtime

  • Type: boolean

  • Optional

Use the system runtime instead of a containerized environment.

--no-cache

  • Type: boolean

  • Optional

Disable caching.

--verbose

  • Type: boolean

  • Optional

Enable verbose output.

--secrets

  • Type: boolean

  • Optional

Fetch and inject secrets into the policy execution environment.

Example

lunar policy ok-release

  • Form:

The lunar policy ok-release command is used to check if a component at a specific git SHA passes its release policies.

Either both positional arguments must be provided, or neither. When no arguments are given, both LUNAR_COMPONENT_ID and GITHUB_SHA environment variables must be set — outside GitHub Actions, including in GitLab CI, pass the component and SHA as arguments instead.

<component>

  • Type: string

The name of the component to check. Falls back to the LUNAR_COMPONENT_ID environment variable when no arguments are given.

<git_sha>

  • Type: string

The git SHA to check. Falls back to the GITHUB_SHA environment variable when no arguments are given. Unlike bypass-release / bypass-pr, this gate does not read CI_COMMIT_SHA.

--poll-interval <duration>

  • Type: duration

  • Optional

  • Default: 10s

How often to poll for results.

--timeout <duration>

  • Type: duration

  • Optional

  • Default: 10m

Maximum time to wait for results before timing out.

--workflow-id <id>

  • Type: string

  • Optional

The CI workflow ID to associate with the check. Auto-detected from GITHUB_RUN_ID; it has no equivalent on GitLab, where Lunar does not record CI runs.

--pr <pr-number>

  • Type: integer

  • Optional

The PR number to check policies for. Auto-detected from GITHUB_REF when running in GitHub Actions — in any other CI, including GitLab, pass it explicitly. On GitLab, use the merge request's number.

--fail-open[=<mode>]

  • Type: string

  • Optional

  • Default: unset (the gate fails when it cannot get a verdict)

  • Values: unreachable (the default when the flag is given without a value), timeout, both

Exit 0 instead of erroring when Lunar Hub could not produce a verdict, so an outage never stalls a deploy or a merge. Must be written as --fail-open=<mode>; a bare --fail-open means unreachable.

Fail-open trips on unavailability, never on a verdict — a component that genuinely fails a blocking policy still exits 1 under every mode.

Mode
Unblocks on

unreachable

No verdict could be obtained because Lunar Hub was not serving: unreachable from the first call, contact lost mid-poll, rejecting under load, or never answering a single poll before --timeout.

timeout

Lunar Hub was answering — reporting the evaluation as still running — but never finished it before --timeout.

both

Either of the above.

timeout is deliberately opt-in. A timeout while Lunar Hub is up and evaluating is a verdict still in progress, not an outage, so unblocking on it can let a slow-but-genuinely-blocking evaluation through — especially with a short --timeout.

Authentication, authorization and unknown-component errors are always fatal, under every mode.

Every fail-open event is logged to standard error.

lunar policy ok-pr

  • Form:

The lunar policy ok-pr command is used to check if a component at a specific git SHA passes its PR policies.

Either both positional arguments must be provided, or neither. When no arguments are given, both LUNAR_COMPONENT_ID and GITHUB_SHA environment variables must be set — outside GitHub Actions, including in GitLab CI, pass the component and SHA as arguments instead.

<component>

  • Type: string

The name of the component to check. Falls back to the LUNAR_COMPONENT_ID environment variable when no arguments are given.

<git_sha>

  • Type: string

The git SHA to check. Falls back to the GITHUB_SHA environment variable when no arguments are given. Unlike bypass-release / bypass-pr, this gate does not read CI_COMMIT_SHA.

--poll-interval <duration>

  • Type: duration

  • Optional

  • Default: 10s

How often to poll for results.

--timeout <duration>

  • Type: duration

  • Optional

  • Default: 10m

Maximum time to wait for results before timing out.

--workflow-id <id>

  • Type: string

  • Optional

The CI workflow ID to associate with the check. Auto-detected from GITHUB_RUN_ID; it has no equivalent on GitLab, where Lunar does not record CI runs.

--pr <pr-number>

  • Type: integer

  • Optional

The PR number to check policies for. Auto-detected from GITHUB_REF when running in GitHub Actions — in any other CI, including GitLab, pass it explicitly. On GitLab, use the merge request's number.

--fail-open[=<mode>]

  • Type: string

  • Optional

  • Default: unset (the gate fails when it cannot get a verdict)

  • Values: unreachable (the default when the flag is given without a value), timeout, both

Exit 0 instead of erroring when Lunar Hub could not produce a verdict, so an outage never stalls a deploy or a merge. Must be written as --fail-open=<mode>; a bare --fail-open means unreachable.

Fail-open trips on unavailability, never on a verdict — a component that genuinely fails a blocking policy still exits 1 under every mode.

Mode
Unblocks on

unreachable

No verdict could be obtained because Lunar Hub was not serving: unreachable from the first call, contact lost mid-poll, rejecting under load, or never answering a single poll before --timeout.

timeout

Lunar Hub was answering — reporting the evaluation as still running — but never finished it before --timeout.

both

Either of the above.

timeout is deliberately opt-in. A timeout while Lunar Hub is up and evaluating is a verdict still in progress, not an outage, so unblocking on it can let a slow-but-genuinely-blocking evaluation through — especially with a short --timeout.

Authentication, authorization and unknown-component errors are always fatal, under every mode. Otherwise an expired token, or one typo in a shared pipeline template, would silently turn every gate into a no-op that never goes red.

Every fail-open event is logged to standard error.

Bypassing a block

lunar policy ok-release and lunar policy ok-pr exit 1 when a blocking policy fails. A bypass overrides that verdict for a bounded window, so a known failure can be shipped past without disabling the policy for everyone.

Command
Purpose

lunar policy bypass-release

Override the release gate for a component

lunar policy bypass-pr

Override the PR/MR merge gate for a component

lunar policy bypass-ls

List a component's bypasses

lunar policy bypass-rm

Revoke a bypass early

Three properties hold for every bypass:

  • It always expires. There is no way to create one that lasts forever. Omitting --for uses the configured bypass.max_duration — never infinity — because a bypass that never expires is a silently disabled policy that nothing would ever surface again.

  • It is audited, not authorized. The actor is recorded but not verified: these commands are trusted-by-token, so anyone holding a Lunar Hub token can run them.

  • It never goes silently green. A gate cleared by a bypass still prints every check that was suppressed, who authorized it, and until when:

    A partially bypassed gate still fails: checks the bypass does not cover keep blocking.

Both the bypasses and the individual checks they suppressed are queryable over the SQL API, through the bypasses and bypassed_checks views.

Scope

A bypass covers one component and one gate, optionally narrowed by SHA, PR number, and policy. Any narrowing dimension left unset matches every value of it — that is what makes a bypass component-wide.

  • The gate is not transitive. A policy that blocks both PRs and releases fails in each gate separately and needs a bypass in each. Clearing a PR merge never silently clears a deploy.

  • --policy names either a whole plugin (sbom) or a single check (sbom.no-critical-vulns).

  • A component-wide bypass has to be narrowed on purpose. With no --sha, --pr or --policy it masks every failing blocking check for the gate, including policies added to the configuration after it was created. Lunar Hub rejects that blast radius unless it is narrowed, or given a window chosen rather than inherited:

In CI, when neither --sha nor --pr is given, the commit is inferred from GITHUB_SHA or CI_COMMIT_SHA and the bypass is scoped to it. A SHA-scoped bypass dies on the next push, which is a tighter bound than any clock. Outside CI there is no SHA to infer, so the bypass stays component-wide and the rule above applies.

When several active bypasses cover the same check, the first match wins. Since each one is a deliberate override in its own right, which one wins affects only the actor the output credits, not what is masked.

Durations

--for, and bypass.max_duration that caps it, accept Go's duration grammar extended with d (24 hours) and w (7 days) units. The units may be mixed: 36h, 3d, 2w, 1w2d, 1d12h30m.

A --for longer than bypass.max_duration is rejected, not shortened. Silently clamping it would let you believe a two-week waiver is in place when it expires in two days.

lunar policy bypass-release

  • Form:

Records a time-bound override of a component's release block, so lunar policy ok-release passes for as long as it lasts.

The command prints the stored record, including the id needed to revoke it.

<component>

  • Type: string

  • Optional

The component to override. Falls back to the LUNAR_COMPONENT_ID environment variable when no argument is given.

--reason <text>

Why the block is being overridden. An unexplained override is not much of an audit trail, which is why this is required by default.

--sha <git-sha>

  • Type: string

  • Optional

  • Default: GITHUB_SHA or CI_COMMIT_SHA, when neither --sha nor --pr is given

Limit the bypass to one commit.

--pr <pr-number>

  • Type: integer

  • Optional

Limit the bypass to one PR or MR number.

--policy <selector>

  • Type: string

  • Optional

Limit the bypass to one plugin (sbom) or one check (sbom.no-critical-vulns). Unset covers every blocking check for the gate.

--for <duration>

  • Type: duration

  • Optional

  • Default: the configured bypass.max_duration

How long the bypass lasts. Rejected if it exceeds the configured cap.

--actor <name>

  • Type: string

  • Optional

  • Default: GITLAB_USER_LOGIN, GITHUB_ACTOR, or USER

Who is overriding the block. Recorded unverified — the output labels it as such. The command fails if no actor can be determined.

lunar policy bypass-pr

  • Form:

Records a time-bound override of a component's PR/MR merge block, so lunar policy ok-pr passes for as long as it lasts.

On GitLab, the bypass also clears the MR's Earthly Lunar signal — the external status check where the merge gate is live, or the commit status (what Pipelines must succeed gates on) elsewhere: the checks it covers stop counting against the rollup, and the MR comment lists each of them with who bypassed it and until when. The signal is pushed, not polled — it updates on the next policy evaluation (a new commit, a collection), not the moment the bypass is created or expires.

Takes exactly the same arguments and flags as lunar policy bypass-release; only the gate differs. A bypass on one gate has no effect on the other, so a policy that blocks both PRs and releases needs one of each.

lunar policy bypass-ls

  • Form:

Lists a component's bypasses, newest first. Expired and revoked records are included by default.

scope reads entire component, every blocking check when nothing narrows the bypass, and status is one of active, expired, or revoked <when> by <who>.

<component>

  • Type: string

  • Optional

The component whose bypasses to list. Falls back to LUNAR_COMPONENT_ID.

--active

  • Type: boolean

  • Optional

  • Default: false

Show only bypasses that are neither expired nor revoked.

--sha <git-sha>

  • Type: string

  • Optional

Show only bypasses that cover this SHA.

--pr <pr-number>

  • Type: integer

  • Optional

Show only bypasses that cover this PR or MR number.

lunar policy bypass-rm

  • Form:

Ends a bypass before it expires, taking the block that it was masking back into effect.

This is a revoke, not a delete: the record survives with the revoker and timestamp attached, and still appears in bypass-ls without --active. Revoking an id that does not exist, or one that is already revoked, is an error.

<bypass-id>

  • Type: string

  • Required

The id of the bypass to revoke, as printed by bypass-ls or by the command that created it.

--actor <name>

  • Type: string

  • Optional

  • Default: GITLAB_USER_LOGIN, GITHUB_ACTOR, or USER

Who is revoking the bypass. Recorded unverified, like the creating actor.

SDK Commands

lunar catalog

Saves catalog-related information from within a cataloger.

For detailed documentation on the lunar catalog command and all its options, see the Cataloger Bash SDK page.

lunar collect

Collects SDLC metadata into a component's JSON. Pass --component and --sha to collect against a specific component and commit from anywhere.

For detailed documentation on the lunar collect command and all its options, see the Collector Bash SDK page.

SQL Commands

lunar sql connection-string

  • Form:

The lunar sql connection-string command returns the PostgreSQL connection string that can be used with any PostgreSQL client. The access is read-only and restricted to only the views described in the SQL API documentation.

Example:

For more examples of the SQL API in action, see the SQL API documentation.

lunar secret set

Set a secret that will be available to collectors, policies, or catalogers as LUNAR_SECRET_<NAME>.

If value is omitted, it is read from stdin (recommended for sensitive values to avoid shell history exposure).

Typing the value at the prompt? End it with Ctrl+D to signal EOF. With value omitted, lunar secret set reads stdin until end-of-input.

Secrets are encrypted at rest using AES-256-GCM. The Hub must have HUB_SECRETS_ENCRYPTION_KEY configured.

Options

  • --scope <scope> — Secret scope: collector (default), policy, or cataloger.

Examples

lunar secret delete

Delete a previously configured secret.

Options

  • --scope <scope> — Secret scope: collector (default), policy, or cataloger.

Examples

lunar secret list

List the names of configured secrets for a given scope. Values are never displayed.

Options

  • --scope <scope> — Secret scope: collector (default), policy, or cataloger.

Examples

Queue Commands

Collectors, policies and catalogers are dispatched through a queue and executed in the background. These commands let you inspect that queue and empty it, which is how you recover when a misconfiguration has filled it with work that can only fail and retry.

Jobs that are already running are never deleted. They finish on their own.

lunar queue status

Show how many snippet executions are queued, broken down by type.

  • CLEARABLE — jobs lunar queue clear would delete: waiting to start, plus backing off after a failure.

  • RETRYING — the subset of clearable jobs that have already failed at least once. A large number here is the signature of a failure loop.

  • RUNNING — currently executing. Never deleted by a clear.

  • DISCARDED — out of retries. These consume no capacity and are cleaned up automatically, so a clear leaves them alone.

lunar queue clear

Delete queued snippet executions of the given type.

Run it without --yes first: it prints exactly what would be removed and stops without deleting anything. Add --yes to go through with it. There is no interactive prompt, so the command behaves identically in a terminal, through a pipe, and in CI.

Cleared jobs are gone — they are not rescheduled. Collectors and policies re-run on the next push to a component, but any result that a cleared job would have produced for an in-flight commit will be missing until then.

Options

  • --yes — Actually delete. Without it the command previews and exits.

Examples

If the queue still shows running jobs after a clear, that is expected — a clear never interrupts work in progress.

Utility Commands

lunar clear-cache

  • Form:

The lunar clear-cache command deletes Git and installation file caches used by Lunar. This can be useful to resolve issues caused by stale cached data.

lunar version

  • Form:

The lunar version command prints the Lunar CLI version and commit SHA.

PreviousCatalog JSON
Nextlunar-config.yml

Last updated