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:
stringOptional
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:
stringOptional
Override the host name of the Lunar Hub. This setting is inferred from the Lunar config if not specified.
Correct:
hub.example.commyhost
Incorrect:
https://hub.example.comhttp://hub.example.comhub.example.com:8080myhost:443
--hub-grpc-port <port>, LUNAR_HUB_GRPC_PORT=<port>
Type:
integerOptional
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:
integerOptional
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:
booleanOptional
If true, use insecure HTTP connections to the Hub server.
--no-hub, LUNAR_NO_HUB=true
Type:
booleanOptional
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:
stringOptional 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:
stringOptional
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:
LUNAR_GITHUB_TOKENorLUNAR_GITLAB_TOKENThe token stored by
lunar loginFor a service-token caller, a Hub-vended credential
For every other caller, the token from
ghorglab
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
Requires:
public
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
Requires:
authenticated
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
Requires:
authenticated
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:
stringRequired (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:
stringRequired
Kubernetes namespace for the Secret.
--name <name>
Type:
stringOptional
Default:
regcred
Kubernetes Secret name. The Hub chart's imagePullSecrets reference defaults to regcred.
--out <path> | -o
Type:
stringOptional
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-collectorsand--cancel;--dry-runruns 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:
stringForm:
github://<owner>/<repo>[/<config-path>]@<branch-or-sha>orgitlab://<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@maingithub://acme-corp/lunar@de4adbeefgitlab://gitlab.com/acme-corp/lunar@maingitlab://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:
booleanOptional
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:
booleanOptional
Rerun affected code collectors after applying the configuration.
--include-pr-commits
Type:
booleanOptional
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:
integerOptional
Default:
5
Ignore PR commits older than this maximum number of days.
--rerun-catalogers | -t
Type:
booleanOptional
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, repeatableOptional
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:
stringOptional
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
Form:
Requires:
hub.pull
The lunar hub run-code-collectors command instructs Lunar Hub to rerun code collectors.
--pr-max-age-days <days>
Type:
integerOptional
Default:
5
Ignore PR commits older than this maximum number of days.
--include-pr-commits
Type:
booleanOptional
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
Form:
Requires:
authenticated;--defaultsrequires nothing
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: includeinternal,authenticated, andpublic--defaults: print built-in defaults without contacting the Hub--output-json: print the full table as JSON
lunar hub merge-gate
Form:
Requires:
hub.readforstatusand to preview;hub.operateto switch with--yes
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:
stringOptional
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:
stringOptional (
offonly)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:
stringRequired for
off, optional foron
Recorded in the ledger.
--actor <name>
Type:
stringOptional
Who is switching, when using the service token. A logged-in user is recorded as themselves.
--yes
Type:
booleanOptional
Switch. Without it the command previews and exits.
--output-json
Type:
booleanOptional (
statusonly)
Print the status as JSON.
Examples
lunar hub recovery
Form:
Requires:
hub.readfor status and previews;hub.operateto 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:
--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-releaseandlunar policy ok-prreport 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 --skippedlists 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
Form:
Requires:
admin.read
The lunar hub get-logs command retrieves logs from Lunar Hub.
--namespace <namespace> | -n
Type:
stringOptional
The Kubernetes namespace to retrieve logs from.
--output <format> | -o
Type:
stringOptional
Output format for the logs.
--tail <lines>
Type:
integerOptional
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
Form:
The lunar domain ls command is used to list all domains.
Component Commands
lunar component ls
Form:
The lunar component ls command is used to list all components.
lunar component get-json
Form:
Requires:
components.read
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:
stringOptional
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:
integerOptional
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:
booleanOptional
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:
Requires:
components.read
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:
stringOptional
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/repohooks) returns a single delta. Passing--componentis rejected.A per-component cataloger (any
component-cron/component-repohook) stores one delta per component.--componentis required; omitting it is rejected with a "per-component scoped" error.
--component <name>
Type:
stringOptional
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:
stringOptional
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 as2026-05-01T00:00:00Z)Date + time without timezone:
2026-05-01T12:34:56(interpreted as UTC)Full RFC3339:
2026-05-01T12:34:56Zor2026-05-01T12:34:56-07:00
--pretty | -p
Type:
booleanOptional
Pretty-print the JSON output.
Examples:
lunar cataloger run
Form:
Requires:
components.run, plushub.readto poll the jobs it started
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:
stringOptional
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:
stringOptional
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:
booleanOptional
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-hubruns 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:
stringOptional
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:
stringOptional
Look the component up in the resolved manifest. Required when running a per-component cataloger. Mutually exclusive with --component-dir.
--component-dir <path>
Type:
stringOptional
Treat the given local directory as the component checkout (no clone). Mutually exclusive with --component and --config.
--config <repo>
Type:
stringOptional
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:
stringOptional
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.
--script <path>
Type:
stringOptional
Override the cataloger's main script with a local file path. Combine with --script-lang to control the runtime used.
--script-lang <language>
Type:
stringOptional
Default:
bash
Language for --script (bash / python / node).
--use-system-runtime
Type:
booleanOptional
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:
booleanOptional
Delete cacheable temporary files before running. Use this to force a clean run when troubleshooting.
--verbose
Type:
booleanOptional
Stream the cataloger's engine stdout / stderr to the terminal as it runs.
--secrets <k=v,k=v>
Type:
stringOptional
Supplemental secrets injected into the cataloger's environment, parsed as comma-separated key=value pairs.
--output-json
Type:
booleanOptional
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:
Requires:
components.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.
<component-name>
Type:
stringOptional
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:
integerOptional
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:
stringOptional
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:
stringOptional
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:
integerOptional
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-hubruns 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:
stringRequired in Name Form
--script <path-to-collector-script>
Type:
stringRequired 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:
integerOptional
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:
stringOptional
The specific git SHA to run collectors for. If specified, this takes precedence over --pr.
<collector-name>
Type:
stringOptional
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:
stringOptional
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:
stringOptional
Remote config repository to use.
--use-system-runtime
Type:
booleanOptional
Use the system runtime instead of a containerized environment.
--no-cache
Type:
booleanOptional
Disable caching.
--verbose
Type:
booleanOptional
Enable verbose output.
--merge
Type:
booleanOptional
Merge the collected data into the existing component JSON.
--secrets
Type:
booleanOptional
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-hubto skip Hub entirely, and--scriptto 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
Form:
The lunar policy ls command is used to list all policies.
lunar policy check ls
Form:
The lunar policy check ls command is used to list all checks.
lunar policy run
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:
integerOptional
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:
stringOptional
The specific git SHA to rerun policies for. If specified, this takes precedence over --pr.
--policy <policy-name>
Type:
stringOptional
Repeatable
Run only the specified policy. This flag can be repeated to run multiple specific policies.
--initiative <initiative-name>
Type:
stringOptional
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, andcomponents.readwith--component.--no-hubtogether with--component-jsonruns 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:
stringRequired in Name Form
--script <path-to-policy-script>
Type:
stringRequired 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:
integerOptional
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:
stringOptional
The specific git SHA to run the policy against. If specified, this takes precedence over --pr.
--with <args>
Type:
stringOptional
Arguments passed to the policy script.
--script-lang <language>
Type:
stringOptional
Default:
python
The script programming language.
--output <format>
Type:
stringOptional
Values:
json,list
Output format for the policy results.
--config <repo>
Type:
stringOptional
Remote config repository to use.
--use-system-runtime
Type:
booleanOptional
Use the system runtime instead of a containerized environment.
--no-cache
Type:
booleanOptional
Disable caching.
--verbose
Type:
booleanOptional
Enable verbose output.
--secrets
Type:
booleanOptional
Fetch and inject secrets into the policy execution environment.
Example
lunar policy ok-release
Form:
Requires:
components.read
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:
durationOptional
Default:
10s
How often to poll for results.
--timeout <duration>
Type:
durationOptional
Default:
10m
Maximum time to wait for results before timing out.
--workflow-id <id>
Type:
stringOptional
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:
integerOptional
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:
stringOptional
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.
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:
Requires:
components.read
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:
durationOptional
Default:
10s
How often to poll for results.
--timeout <duration>
Type:
durationOptional
Default:
10m
Maximum time to wait for results before timing out.
--workflow-id <id>
Type:
stringOptional
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:
integerOptional
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:
stringOptional
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.
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.
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
--foruses the configuredbypass.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 standsin place ofuntil <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.
--policynames 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--policybypass never clears a stuck check; use--shawithout--policyfor that.A component-wide bypass has to be narrowed on purpose. With no
--sha,--pror--policyit 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:
Requires:
bypasses.manage
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:
stringOptional
The component to override. Falls back to the LUNAR_COMPONENT_ID environment variable when no argument is given.
--reason <text>
Type:
stringRequired, unless
bypass.require_reasonisfalse
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:
stringOptional
Default:
GITHUB_SHAorCI_COMMIT_SHA, when neither--shanor--pris 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:
integerOptional
Limit the bypass to one PR or MR number.
--policy <selector>
Type:
stringOptional
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:
durationOptional
Default: the configured
bypass.max_duration
How long the bypass lasts. Rejected if it exceeds the configured cap.
--actor <name>
Type:
stringOptional
Default: the authenticated login, the CI job's OIDC actor, or
GITLAB_USER_LOGIN,GITHUB_ACTOR, orUSERwith 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
Form:
Requires:
bypasses.manage
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
Form:
Requires:
components.read
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:
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:
(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:
stringOptional
The component whose bypasses to list. Falls back to LUNAR_COMPONENT_ID.
--active
Type:
booleanOptional
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:
stringOptional
Show only bypasses that cover this SHA.
--pr <pr-number>
Type:
integerOptional
Show only bypasses that cover this PR or MR number.
lunar policy bypass-rm
Form:
Requires:
bypasses.manage
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:
stringRequired
The id of the bypass to revoke, as printed by bypass-ls or by the command that created it.
--actor <name>
Type:
stringOptional
Default: verified login, or
GITLAB_USER_LOGIN,GITHUB_ACTOR, orUSERwith 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.collectwhen 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
Form:
Requires:
sql.connect, oradmin.readwith--grafana
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
Form:
Requires:
admin.read
Lists personal SQL credentials and their status. --output-json prints the same audit rows as JSON.
lunar sql credentials revoke
Form:
Requires:
hub.operate
Disables the person's SQL role and terminates its sessions. They can mint another credential while they retain sql.connect.
lunar secret set
Requires:
secrets.write
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, orcataloger.--file <path>— Read the value from this file. Cannot be combined withvalue.
Examples
lunar secret delete
Requires:
secrets.write
Delete a previously configured secret.
Options
--scope <scope>— Secret scope:collector(default),policy, orcataloger.
Examples
lunar secret list
Requires:
secrets.read
List the names of configured secrets for a given scope. Values are never displayed.
Options
--scope <scope>— Secret scope:collector(default),policy, orcataloger.
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 addregisters 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
administrationwould 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
Form:
Requires:
secrets.write
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.pemprivate 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. Defaultgithub.com.--base-url <url>— The REST API URL, when it is neitherhttps://api.github.comnorhttps://<host>/api/v3.
Examples
lunar github-app list
Form:
Requires:
secrets.read
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
Form:
Requires:
secrets.write
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
Form:
Requires:
hub.operate
Lists the events a subscription can name, each with the fields of its payload as paths a filter can use.
lunar webhooks subscribe
Form:
Requires:
hub.operate
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
Form:
Requires:
hub.operate
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
Form:
Requires:
hub.operate
Lists the subscriptions with their full URL, events, filter, state and last delivery. Never their secrets.
lunar webhooks update
Form:
Requires:
hub.operate
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
Form:
Requires:
hub.operate
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
Form:
Requires:
hub.operate
Shows one delivery: the payload sent and every attempt, with its HTTP status, duration, error and the receiver's answer.
lunar webhooks redeliver
Form:
Requires:
hub.operate
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
Form:
Requires:
hub.operate
Sends the subscription a ping now, even while it is paused.
lunar webhooks resume
Form:
Requires:
hub.operate
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
Form:
Requires:
hub.operate
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
Requires:
hub.read
Show how many snippet executions are queued, broken down by type.
CLEARABLE — jobs
lunar queue clearwould 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
Requires:
hub.readto preview, andhub.operateto delete with--yes
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
