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 host name of the Lunar Hub. This setting is inferred from the Lunar config if not specified.

Correct:

  • hub.example.com

  • myhost

Incorrect:

  • https://hub.example.com

  • http://hub.example.com

  • hub.example.com:8080

  • myhost:443

--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 a Git platform token must be set if GitHub or GitLab access is needed.

LUNAR_HUB_TOKEN

  • Type: string

  • Optional once you have run lunar login; otherwise required for commands that interact with the Hub server

When set, this credential takes precedence. Otherwise the CLI uses the session stored by lunar login. See Authorization.

LUNAR_GITHUB_TOKEN, LUNAR_GITLAB_TOKEN

  • Type: string

  • Optional

Git platform tokens for commands that read repositories: lunar hub pull --dry-run, lunar collector dev and lunar policy dev. These commands resolve a credential in this order:

  1. LUNAR_GITHUB_TOKEN or LUNAR_GITLAB_TOKEN

  2. The token stored by lunar login

  3. For a service-token caller, a Hub-vended credential

  4. For every other caller, the token from gh or glab

The last two are alternatives: a service-token caller does not fall through from the Hub to gh or glab. Those CLI credentials provide Git access only; they do not sign in to Lunar Hub.

Login commands

lunar login

Signs in through a configured GitHub or GitLab provider. GitHub uses Device Flow; GitLab uses Device Flow when enabled and PKCE otherwise. The CLI stores and refreshes the login in the OS keyring, or in ~/.lunar/credentials.json with mode 0600.

  • --forge, --host: select a Git platform and host when the Hub accepts more than one

  • --list: list accepted providers and exit

lunar logout

Deletes the stored login and revokes its Git platform token when supported. Otherwise it prints the manual revocation URL. The Hub session expires on its own.

lunar whoami

Prints the current principal, Git platform, host, and credential source. A session expiry is also shown when the credential came from a stored lunar login.

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:

  • Requires: nothing — runs locally, with no Hub call

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:

  • Requires: nothing — runs locally, with no Hub call

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:

  • Requires: nothing — the credential is read from the licence file, with no Hub call

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:

  • Requires: nothing — the schema is generated from the binary, with no Hub call

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:

  • Requires: hub.pull, including with --rerun-code-collectors and --cancel; --dry-run runs locally

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.

<repo>

  • Type: string

  • Form: github://<owner>/<repo>[/<config-path>]@<branch-or-sha> or gitlab://<host>/<namespace>/<project>[/-/<config-path>]@<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.

The optional <config-path> selects which configuration file to load, so one repository can hold several — one per Hub or per environment — and a monorepo can keep its configuration somewhere other than the root. It may name the file itself (github://acme-corp/lunar/lunar-config.dev.yml@main) or a directory holding a lunar-config.yml (github://acme-corp/lunar/configs/dev@main). Omitted, the entry point is lunar-config.yml at the repository root.

A local filesystem path is also accepted, and may likewise name either a directory or the configuration file inside it — useful with --dry-run.

--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 the entry point + its fragments, resolve every uses: plugin, validate the whole manifest, check that the image every collector, policy, and cataloger runs in exists, and resolve each unpinned component's default branch — then stops before persisting. It does not install a script's dependencies, so that one step could still fail on a real pull; see Validating your config for the details.

Public repositories resolve anonymously; private and wildcard repositories use a Git platform token. The Hub checks the configuration's images with its own registry credentials, so the dry run needs a Hub unless --no-hub skips that check. See Script images.

--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. On a pull request, only the components the pull request's changed files matched are rerun, as matched under the configuration in place at its last push: a component added or widened since is picked up at the pull request's next push, and stays on its previous configuration until then. A pull request whose changed files matched no component is skipped; one Lunar Hub never saw a push for reruns every component of its repository.

--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.

--cancel <config-commit-sha>

  • Type: string, repeatable

  • Optional

Cancel a configuration version, named by the full commit SHA of the config repository it was pulled from. Its queued work stops, and every commit it judged is re-evaluated under the configuration that is current once this pull finishes. Repeat the flag to cancel several versions. The cancel applies even when the pulled version was already installed, which is the usual case once the revert has synced. See Cancel a Bad Config for what happens next and what it can't undo.

Lunar Hub refuses a version it doesn't know and the version that is current, and cancels nothing when it refuses any of them. A Lunar Hub that predates --cancel ignores it, so the command fails with the Hub did not confirm canceling version <sha> rather than reporting success.

--actor <name>

  • Type: string

  • Optional

Who --cancel is recorded as. Required with the service token. A logged-in user is recorded as themselves, and a CI job as the person it runs for.

lunar hub run-code-collectors

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

--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. On a pull request, only the components the pull request's changed files matched are rerun, as matched under the configuration in place at its last push: a component added or widened since is picked up at the pull request's next push, and stays on its previous configuration until then. A pull request whose changed files matched no component is skipped; one Lunar Hub never saw a push for reruns every component of its repository.

lunar hub permissions

Prints the effective permission table. * marks configured role overrides. A note under the table says when the connected Hub lets configuration repository administrators past it.

  • --verbose: include each RPC and its request checks

  • --all: include internal, authenticated, and public

  • --defaults: print built-in defaults without contacting the Hub

  • --output-json: print the full table as JSON

lunar hub merge-gate

The lunar hub merge-gate command switches Lunar-managed merge requirements on GitHub and GitLab off and back on without a redeploy. On GitLab it also controls Lunar's project badges and passing commit statuses on merge requests with nothing to report. The Hub applies a change within minutes of --yes. Every change is recorded in hub.merge_gate_changes, an append-only ledger readable over the SQL API.

Like lunar queue clear, off and on print what they would do and exit without --yes.

status

Lists the rules in force, least specific first, with who set each, why and until when (never for an off that stands until switched back on), and how many projects the Hub has still to converge. The first line shows the operator's flags: with HUB_GITLAB_MERGE_GATE_ENABLED=false the gate is off whatever the rules say.

off

By default, --hard disables Lunar-managed requirements. On GitLab it removes the external status check, so open merge requests fall back to a commit status. --soft keeps the requirement registered and passes Lunar checks on open PR/MR heads with a soft-off notice. Policies continue to evaluate; their results and comments retain the actual verdict. Both modes remove Lunar's GitLab badges until the gate is back on. The off stands until on switches it back, or until --for runs out.

on

Switches its scope on: the scope's own off is retired and, while a broader off still covers it, the scope is pinned on underneath that off for as long as it stands (status shows the pin as on, expiring with the off). On GitLab the check is re-created, answering passed for every merge request open at that moment, and badges return on each project's next default-branch evaluation. A narrower off keeps its own expiry. To stage a rollout, switch every project off and pin groups on one at a time.

--group <path>

  • Type: string

  • Optional

  • Default: every project

A GitLab group path; its subgroups are included. For GitHub, use --org <org> or --org <org>/<repo> to select an organization or repository.

--for <duration>

  • Type: string

  • Optional (off only)

  • Default: none; the off stands until switched back on

How long the off lasts, such as 4h or 7d. When it runs out the Hub switches the scope back on by itself. Omit it for an off that stands until lunar hub merge-gate on, as in a staged rollout. A Hub that sets HUB_MERGE_GATE_OFF_MAX (unset by default; self-hosted operators set it on the Hub, Lunar Dedicated customers ask Earthly) makes every off expire: --for then defaults to it and may not exceed it, with a longer value rejected rather than shortened.

--reason <text>

  • Type: string

  • Required for off, optional for on

Recorded in the ledger.

--actor <name>

  • Type: string

  • Optional

Who is switching, when using the service token. A logged-in user is recorded as themselves.

--yes

  • Type: boolean

  • Optional

Switch. Without it the command previews and exits.

--output-json

  • Type: boolean

  • Optional (status only)

Print the status as JSON.

Examples

lunar hub recovery

  • Form:

  • Requires: hub.read for status and previews; hub.operate to enter, exit, or replay with --yes

Recovery mode stops ordinary work while the Lunar Hub stays available for the SQL API, diagnostics, and repair commands such as lunar hub pull --cancel. The Hub records every entry, extension, exit, expiry, and explicit replay in the append-only hub.recovery_mode_changes ledger.

Choose how recovery handles Lunar's merge requirements:

Mode
Behavior

--hard (default)

Opens configured Lunar-managed merge gates

--soft

Passes failed and in-flight Lunar checks on current open PR/MR heads, including new heads arriving during recovery

--both or --soft --hard

Applies both operations

Recovery success bypasses policy evaluation. GitHub check runs and GitLab commit statuses carry a recovery notice. Other providers' checks and gates are unchanged. Upgrade every Hub replica before selecting soft or combined recovery. The mode is fixed when the window opens and survives extensions and restarts.

While recovery mode is on:

  • Ordinary work stops. Queued collection, policy, posting, repository-sync, cataloger, and webhook-upkeep jobs are canceled rather than held for exit. Queued script execution is purged; scripts already running can finish. Incoming data from CI is acknowledged and dropped, or stored without evaluation when the window is retained.

  • Normal git-platform posting stops. Lunar suppresses evaluation reports, comments, and badges. Soft or combined recovery passes Lunar checks without evaluation. On GitLab, required status replies and authenticated external-check callbacks, including Retry, also pass in these modes.

  • Release gates pass without evaluation. lunar policy ok-release and lunar policy ok-pr report that recovery mode is active and the commit was not evaluated.

  • Webhook metadata stays current. Lunar records pull requests, commits, and CI runs from incoming payloads. status --skipped lists open PR/MR heads left unevaluated, distinguishing heads that arrived during recovery from evaluations already in flight at entry.

The skipped-head listing can time out on large fleets. Basic status without --skipped remains available; a listing timeout does not mean there were no skipped heads.

on without --for lasts until you turn it off. With --for, the Hub expires the window as the system actor. Running on again resets expiry from the current time, or clears it if --for is omitted. --actor is required with the service token; a logged-in user is recorded as themselves. Commands preview their effects and exit without changing anything unless you pass --yes.

Exit and optional replay

off starts normal work again and spreads overdue repository syncs over the configured reconcile window. Sync catches up metadata; it does not evaluate every commit skipped during recovery.

Exit defaults to --restore hold: gates opened by hard recovery stay open, and checks passed by soft recovery stay successful. Expiry also leaves these effects in place, including after automatic budget entry. --restore now restores gates opened by recovery, preserving pre-existing manual hard offs; it does not reevaluate checks. Use lunar hub merge-gate status to check convergence because work can resume before gate changes reach GitHub or GitLab.

To restore later without changing which GitHub orgs are armed, re-enter recovery with lunar hub recovery on --reason <text> --yes, then exit with lunar hub recovery off --reason <text> --restore now --yes. Re-entering interrupts normal work, can cancel queued evaluation jobs, and replaces the latest window available for replay. An ordinary scoped lunar hub merge-gate on can also arm a previously unarmed GitHub org and enforce checks across its repositories. Review that command's preview before confirming it with --yes.

Soft recovery records affected PR/MR heads before writing success, including heads already evaluated or in flight before entry. off --replay open-heads queues fresh collection and evaluation for recorded heads that are still current and open, without requiring --retain. Replay preserves existing manifest pins and affected components. Soft-passed checks stay green while replay queues and runs; the next evaluation posts the real verdict.

Without --retain, CI data arriving during recovery is dropped. Head replay recollects code; rerun CI if your policies need that dropped data.

Choose --retain when opening the window to also preserve deferred webhook payloads and incoming CI data, at the cost of database writes during the incident. Retained replay includes the latest unevaluated open PR/MR and configured main-branch heads. Other branches, tags, superseded heads, closed/merged PRs, and already-handled heads are ignored. Retained deliveries run through normal evaluation on a throttled queue; HUB_WEBHOOK_REPLAY_MAX_WORKERS defaults to 2. Extensions keep the original retention choice.

If you exit without replaying, lunar hub recovery replay --reason <text> --yes can replay the most recent recovery window if it used soft recovery or --retain. Repeated requests deduplicate already-queued work. Tracking still finishing on another replica can miss the snapshot, so rerun replay after tracking completes. Replay is unavailable while recovery is active. Retained delivery rows expire according to HUB_WEBHOOK_DELIVERY_RETENTION (default 30 days); soft-recovery head records do not depend on that retention.

Work without a retained delivery or soft-recovery head record needs a new push or explicit CI rerun. In-band GitHub workflow/comment events, GitLab notes, and Buildkite events have no deferred delivery. A newer push with an expired payload can also prevent main-branch replay when its branch can no longer be determined.

lunar hub get-logs

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

  • Default: 1000

Number of lines to capture from the end of each container's log. Pass -1 to capture the whole log.

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

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. The result includes every collection Lunar Hub has recorded at that commit, including one written a moment earlier, so a collector or CD step can read back data it just submitted. If not specified, the latest component JSON is retrieved, which can trail a fresh write by a short while.

--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, the Component JSON is the same with or without it, because it is recorded per commit; 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

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

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:

  • Requires: secrets.read, since the cataloger runs with the secrets it would get on the Hub. --no-hub runs without any Hub call.

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

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, and pass --all, to cover every component, across both code and cron collectors. The code leg also covers recent PR commits, bounded by --pr-max-age-days.

--all

Rerun every component. Required when no component name is given; without it, nothing runs. Cannot be combined with a component name.

--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. On its own, the commit is rerun as seen on the primary branch. With --pr, it is rerun as that PR saw it, which is how an earlier commit of a PR, or one that only exists on a PR branch, is rerun; the commit must belong to that 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:

  • Requires: secrets.read, since the collector runs with the secrets it would get on the Hub. --no-hub runs without any Hub call.

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.

--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> resolves and clones the component through a Git platform token. Without access, the command 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:

  • Requires: secrets.read, and components.read with --component. --no-hub together with --component-json runs without any Hub call.

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

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.

The verdict block this prints can be replaced with your own wording through customization.ok_release_template. The exit code is unaffected.

<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

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. A pull or merge request can also be bypassed from its own thread with a /lunar bypass comment; that override is pinned to a commit rather than time-bound, but lands on the same ledger as the commands below.

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 these commands create. The expiry property does not hold for a comment-driven one, which is bound to a commit rather than a clock and carries a role the Git platform verified.

  • 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.

  • It is authorized and audited. A logged-in user needs bypasses.manage, and the Hub records their verified login and role. A CI job holds it for its own repository and commit, and the Hub records the actor from the OIDC token its Git platform signed, without claiming a human role was checked. The service token grants the permission directly, so its caller-supplied actor is recorded as unverified.

  • 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 commit-bound bypass reads while its commit stands in place of until <timestamp>. 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). It forgives that policy's failures only. A pending check is not failing, so a --policy bypass never clears a stuck check; use --sha without --policy for that.

  • 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

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

Creating or revoking one also refreshes what Lunar reports for the component's default-branch head, re-posting the results already stored for it, so the GitLab project badge catches up without waiting for a push: a fully bypassed component reads release bypassed. The default-branch commit status keeps the un-bypassed verdict, since it gates nothing.

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

A CI job authenticated with its GitHub Actions or GitLab OIDC token may create a bypass only for a component in its own repository, and only for its own commit, which it must name. The default SHA inference supplies that bound for bypass-release, where no dimension is usually given; a request without a SHA is rejected, including a PR-only bypass, which would outlive the head it was granted for. So bypass-pr from a CI job takes both flags, since naming --pr turns the inference off:

Fork pull-request jobs and GitHub pull_request_target jobs cannot write bypasses. A protected ref is not required: the commit is what bounds the job, the same as for other CI writes. The exception is the configuration repository's own pipeline, which administers every component and so may bypass any of them, on a commit it names. That is how a central break-glass job runs on its OIDC identity instead of a stored Hub token.

<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. A CI OIDC job has to name a commit, and naming --pr turns the inference off, so from CI pass this alongside --pr.

--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>

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

--actor <name>

  • Type: string

  • Optional

  • Default: the authenticated login, the CI job's OIDC actor, or GITLAB_USER_LOGIN, GITHUB_ACTOR, or USER with the service token

Logged-in actors are verified; service-token actors are recorded as unverified. A CI job records the actor its Git platform signed, and rejects a --actor naming anyone else.

lunar policy bypass-pr

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.

The bypass also clears the Git platform's Earthly Lunar signal: the GitHub check run that branch protection can require, and on GitLab the external status check where the merge gate is live, or the commit status that Pipelines must succeed reads elsewhere. The checks it covers stop counting against the rollup, and the PR/MR comment lists each of them with who bypassed it and until when. With --sha, Lunar re-posts the signal for that commit as soon as the bypass is created or revoked. Without it, the signal 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.

From a CI OIDC job this takes both --sha "$GITHUB_SHA" and --pr, since such a job must name a commit and naming --pr turns the SHA inference off.

lunar policy bypass-ls

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. source is where the bypass came from: cli, github, gitlab, or ui.

status names why a bypass is or is not in effect, and matches what the Bypasses dashboard reports:

Status
Meaning

active

Still masks its checks.

revoked <when> by <who>

Ended early with bypass-rm.

spent — PR #N was merged or closed

A PR-gate bypass whose PR is finished; nothing is left to authorize.

superseded — a later push moved PR #N past sha <sha>

A PR-gate bypass pinned to a commit the PR head has since moved past; the new push re-armed the gate.

expired

Its --for window ran out.

The last two are the reason a commit-bound bypass (expires: never) can still be inactive: its bound is the commit and the PR, not the clock.

A comment-driven bypass reads differently on two lines, since the platform verified who asked and the commit is the bound:

The label after the actor says what the Hub checked when the bypass was created. The dashboards' Role column carries the same distinction:

Label
Role column
Meaning

(verified: <role>)

<role>

A signed-in user or a Git platform comment. The Hub verified that the actor holds this role on the component.

(CI identity, authorized via OIDC)

ci (oidc)

A CI job, authorized through the OIDC token its Git platform signed. The actor is who the token says triggered the job; no human role was checked, because the job's own repository and commit are what authorized it. This is the expected label for a bypass created from CI.

(CI job of the configuration repository <repo>)

ci job of <repo>

The Lunar configuration repository's own pipeline, which may bypass any component.

(unverified)

unverified

The Hub service token. The actor is whatever the caller supplied, and nothing checked it. Only these rows match the dashboards' Unverified status filter.

<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 with status: active — not expired, not revoked, and for PR-gate bypasses, not superseded by a newer push and not on a merged or closed PR.

--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

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: verified login, or GITLAB_USER_LOGIN, GITHUB_ACTOR, or USER with the service token

Logged-in actors are verified; service-token actors are recorded as unverified.

SDK Commands

lunar catalog

Saves catalog-related information from within a cataloger.

  • Requires: nothing — it writes to the cataloger's output, with no Hub call

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.

  • Requires: components.collect when run out of band. Inside a collector it writes to the collector's output, with no Hub call.

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

SQL Commands

lunar sql connection-string

Returns the shared read-only SQL user for the service token, a personal role for lunar login, and PermissionDenied for CI identity. See SQL API credentials.

Example:

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

lunar sql credentials ls

Lists personal SQL credentials and their status. --output-json prints the same audit rows as JSON.

lunar sql credentials revoke

Disables the person's SQL role and terminates its sessions. They can mint another credential while they retain sql.connect.

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, as it keeps the secret out of your shell history. At a terminal Lunar prompts for the value and does not echo what you type; Enter submits it. Piped or redirected input is read to end-of-input instead, so it may span several lines.

Multi-line material such as a PEM key is best passed with --file, which the terminal prompt does not accept.

A trailing newline is dropped from whatever stdin or --file supplies, so echo and a file that ends in a newline both store the value without it.

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.

  • --file <path> — Read the value from this file. Cannot be combined with value.

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

GitHub App Commands

Collectors and catalogers that call the GitHub API can mint a short-lived installation token from a GitHub App instead of reading a personal access token from a secret. The Hub holds the App's private key, encrypted in the same store as secrets, and mints the tokens itself, so a script only ever sees a token that expires within the hour. Scripts can call lunar github-app get-token once their image ships a Lunar CLI release that includes it.

To set one up, create a GitHub App with the read permissions your collectors and catalogers need and its webhook off, generate a private key, install the App on your organizations, then add it with lunar github-app add. Lunar never creates the App on your behalf, and its key stays in your Hub. Installing the App on more organizations later needs no change in Lunar, but a private App installs only on the account that owns it, so either make it public or add one App per organization under the same name.

Lunar treats these Apps as secrets. Adding or removing one takes secrets.write, and listing them or minting a token takes secrets.read, which collectors and catalogers hold through the Hub's service token.

Give them their own App rather than the Hub's. The Hub's own GitHub App is Lunar's, and lending it to collectors and catalogers costs more than creating a second one:

  • Changing the Hub's App takes a deploy. Its key is a file the Hub reads at boot. lunar github-app add registers an App at runtime, including your own for an off-the-shelf collector that needs different permissions.

  • The Hub's App carries Lunar's write access. It writes checks, PR comments and webhooks, and the tokens the Hub mints from it can't be narrowed. Giving collectors a permission such as administration would mean widening Lunar's own App on every organization, and each organization owner would have to approve the change.

  • Their calls would spend the Hub's rate limit. GitHub limits each App installation separately, so calls through a separate App leave the Hub's budget for webhooks and checks.

lunar github-app add

Adds a GitHub App under <name>, the name plugins mint tokens by. The Hub proves the key with GitHub before storing it and prints the accounts the App is installed on. No command returns the key once it is stored, and lunar secret can't list or change it. Adding an App that <name> already holds on the same host replaces its key, which is how you rotate one.

One name can hold several Apps: one on github.com and one on a GitHub Enterprise Server host, or one per organization. lunar github-app get-token picks the one installed on the owner it is asked about.

The Hub must have HUB_SECRETS_ENCRYPTION_KEY configured.

Options

  • --app-id <id> — The App's ID, from its settings page. Required.

  • --private-key-file <path> — The .pem private key GitHub generated for the App. - reads it from stdin, so the key need not be written to disk. Required.

  • --host <host> — The GitHub host the App lives on. Default github.com.

  • --base-url <url> — The REST API URL, when it is neither https://api.github.com nor https://<host>/api/v3.

Examples

lunar github-app list

Lists the Apps added to the Hub: name, host, App ID, slug, and who stored the current key and when. Keys are never shown.

lunar github-app remove

Removes the Apps stored under <name>, with their keys. --app-id and --host narrow the removal to one App. Tokens already minted stay valid until they expire.

lunar github-app get-token

  • Form:

  • Requires: secrets.read. Collectors, policies and catalogers run with the Hub's service token, which holds it.

Prints an installation token minted from the App named <name>, for its installation on --owner. Inside a collector, policy or cataloger, --owner and --host default to the component's, taken from LUNAR_COMPONENT_ID; anywhere else --owner is required.

--repo narrows the token to some of the owner's repositories, and --permission to some of the App's permissions at read or write. Without them the token can do everything the installation was granted. A permission name GitHub does not define is refused rather than silently dropped.

Tokens last an hour. The Hub mints one per installation and scope and hands the same token to every caller while it has at least 30 minutes left, so a script that runs longer than that asks again.

Examples

Webhook Commands

These manage outbound webhooks: HTTP endpoints the Hub notifies when an event happens.

lunar webhooks events

Lists the events a subscription can name, each with the fields of its payload as paths a filter can use.

lunar webhooks subscribe

Registers url for the events, plus ping, and sends it a ping. Prints the signing secret, which is shown only this once. --filter limits delivery to the events a SQL/JSON path predicate accepts; see Filters.

lunar webhooks filter-test

Evaluates a filter against the most recent deliveries of an event (20 by default, at most 100) and says which it would have delivered. Sends nothing, and exits non-zero on a filter that does not parse.

lunar webhooks ls

Lists the subscriptions with their full URL, events, filter, state and last delivery. Never their secrets.

lunar webhooks update

Changes a subscription's events, filter or description in place, keeping its ID, URL and secret. What is not given is left as it is. --add-event and --remove-event change the current set, --event replaces it; every subscription keeps ping, and at least one event must remain. --filter '' drops the filter. A delivery already queued for an event removed here still goes out. Prints the subscription.

lunar webhooks deliveries

Lists deliveries newest first (50 by default, at most 500), each with its subscription, event, status, number of attempts, creation time and how its last attempt went. --subscription, --event and --status (queued, delivered, failed, filtered or paused) narrow the list, and an unsubscribed subscription's deliveries are still listed. --output-json adds each payload. What the receiver answered is only shown by lunar webhooks delivery.

lunar webhooks delivery

Shows one delivery: the payload sent and every attempt, with its HTTP status, duration, error and the receiver's answer.

lunar webhooks redeliver

Sends a delivery again with the same payload. A paused subscription has to be resumed first, and a delivery that still has an attempt queued, waiting on a retry or running is refused, since that attempt sends it.

lunar webhooks ping

Sends the subscription a ping now, even while it is paused.

lunar webhooks resume

Re-enables a subscription paused after consecutive failed deliveries. Events recorded as paused meanwhile are not sent; redeliver the ones you need.

lunar webhooks unsubscribe

Stops the subscription. Its deliveries are kept, and pending ones are not sent.

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.

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:

  • Requires: nothing — runs locally, with no Hub call

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:

  • Requires: nothing — runs locally, with no Hub call

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

Last updated