Lunar CLI Reference

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

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

Global options

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

• Type: string

• Optional

• Default: .

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

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

• Type: string

• Optional

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

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

• Type: integer

• Optional

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

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

• Type: integer

• Optional

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

--hub-insecure, LUNAR_HUB_INSECURE=true

• Type: boolean

• Optional

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

--no-hub, LUNAR_NO_HUB=true

• Type: boolean

• Optional

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

LUNAR_HUB_TOKEN

• Type: string

• Required for commands that interact with the Hub server

The Lunar Hub token to use for authentication.

Licence Commands

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

Shared options

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

• Type: string

• Required (or set the env var)

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

lunar licence verify

• Form:

  lunar licence verify --licence-file <path>

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:

Licence valid for tenant: acme-corp
Expires:                  2027-12-31 (in 587 days)

GHCR pull credential: configured — run `lunar licence pull-secret` to provision

lunar licence pull-secret

• Form:

  lunar licence pull-secret --licence-file <path> --namespace <ns> [--name <name>] [--out <path>]

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

# Provision the pull secret in the lunar namespace, applied to the cluster directly.
lunar licence pull-secret \
  --licence-file=path/to/hub-licence.jwt \
  --namespace=lunar | kubectl apply -f -

# Same, but for the snippet pods namespace.
lunar licence pull-secret \
  --licence-file=path/to/hub-licence.jwt \
  --namespace=lunar-scripts | kubectl apply -f -

# Write the manifest to disk for GitOps.
lunar licence pull-secret \
  --licence-file=path/to/hub-licence.jwt \
  --namespace=lunar \
  --out=regcred.yaml

lunar licence registry-token

• Form:

  lunar licence registry-token --licence-file <path>

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:

lunar licence registry-token --licence-file=path/to/hub-licence.jwt | \
  docker login ghcr.io -u earthly-bot --password-stdin

Config Commands

lunar hub pull

• Form:

  lunar hub pull [--rerun-code-collectors|-l] [--include-pr-commits] [--pr-max-age-days <days>] [--rerun-catalogers|-t] <repo>

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

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

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

<repo>

• Type: string

• Form: github://<owner>/<repo>@<branch-or-sha>

• 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

--rerun-code-collectors | -l

• Type: boolean

• Optional

Rerun affected code collectors after applying the configuration.

--include-pr-commits

• Type: boolean

• Optional

Include PR commits when rerunning code collectors.

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

• Type: integer

• Optional

• Default: 5

Ignore PR commits older than this maximum number of days.

--rerun-catalogers | -t

• Type: boolean

• Optional

• Default: false

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

lunar hub run-code-collectors

• Form:

  lunar hub run-code-collectors [--pr-max-age-days <days>] [--include-pr-commits]

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

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

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

• Type: integer

• Optional

• Default: 5

Ignore PR commits older than this maximum number of days.

--include-pr-commits

• Type: boolean

• Optional

Include PR commits when running code collectors.

lunar hub get-logs

• Form:

  lunar hub get-logs [--namespace <namespace>] [--output <format>] [--tail <lines>]

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

--namespace <namespace> | -n

• Type: string

• Optional

The Kubernetes namespace to retrieve logs from.

--output <format> | -o

• Type: string

• Optional

Output format for the logs.

--tail <lines>

• Type: integer

• Optional

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

Domain Commands

lunar domain ls

Coming Soon — This feature is not yet available.

• Form:

  lunar domain ls

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:

  lunar component ls

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

lunar component get-json

• Form:

  lunar component get-json [--git-sha <git-sha>] [--pr <pr-number>] [component-name]

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

[component-name]

• Type: string

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

--git-sha <git-sha>

• Type: string

• Optional

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

--pr <pr-number>

• Type: integer

• Optional

The PR number to retrieve the component JSON for. If not specified, and no git SHA is provided, the component JSON for the primary branch will be retrieved. This is ignored if --git-sha is specified.

--pretty | -p

• Type: boolean

• Optional

Pretty-print the JSON output.

Example:

lunar component get-json github.com/my-org/my-repo

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:

  lunar cataloger get-json [--cataloger <name>] [--component <name>] [--ts <timestamp>] [--pretty]

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:

# Latest merged catalog snapshot
lunar cataloger get-json --pretty
# A global cataloger's most recent delta
lunar cataloger get-json --cataloger sbom --pretty
# A per-component cataloger's delta for one component, as of a date
lunar cataloger get-json --cataloger sbom --component github.com/my-org/my-repo --ts 2026-05-01 --pretty

lunar cataloger run

• Form:

  lunar cataloger run [--cataloger <name>] [--component <name>] [--output-json]

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 run --cataloger sbom --component github.com/my-org/my-repo --output-json

lunar cataloger dev

• Form:

  lunar cataloger dev [cataloger-name] \
    [--component <name> | --component-dir <path>] \
    [--config <repo>] \
    [--git-sha <sha>] \
    [--script <path>] [--script-lang <bash|python|node>] \
    [--use-system-runtime] [--no-cache] [--verbose] \
    [--secrets <k=v,k=v>] \
    [--output-json]

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

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

[cataloger-name]

• Type: string

• Optional

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

--component <name>

• Type: string

• Optional

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

--component-dir <path>

• Type: string

• Optional

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

--config <repo>

• Type: string

• Optional

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

--git-sha <sha>

• Type: string

• Optional

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

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

--script <path>

• Type: string

• Optional

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

--script-lang <language>

• Type: string

• Optional

• Default: bash

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

--use-system-runtime

• Type: boolean

• Optional

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

--no-cache

• Type: boolean

• Optional

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

--verbose

• Type: boolean

• Optional

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

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

• Type: string

• Optional

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

--output-json

• Type: boolean

• Optional

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

Example:

lunar cataloger dev sbom --component github.com/my-org/my-repo --verbose

Collector Commands

lunar collector run

Coming Soon — This feature is not yet available.

• Form:

  lunar collector run [--output-json] [--pr <pr-number>] \
    [--git-sha <git-sha>] [--only-code] [--only-cron] \
    [--collector <collector-name>] [--pr-max-age-days <days>] <component-name>

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.

<component-name>

• Type: string

The name of the component to rerun collectors for.

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

--git-sha <git-sha>

• Type: string

• Optional

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

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

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

• Type: integer

• Optional

• Default: 5

Ignore PR commits older than this maximum number of days.

--output-json

Output the results in JSON format.

Example:

# Rerun all collectors for all components for all PRs, limitting to 1 day old PRs
lunar collector run --pr-max-age-days 1
# Rerun collectors for a component (primary branch)
lunar collector run github.com/my-org/my-repo
# Rerun collectors for a specific PR
lunar collector run --pr 123 github.com/my-org/my-repo
# Rerun collectors for a specific git SHA
lunar collector run --git-sha abc123 github.com/my-org/my-repo
# Run only code collectors
lunar collector run --only-code github.com/my-org/my-repo
# Run only a specific collector
lunar collector run --collector collector-name github.com/my-org/my-repo

lunar collector dev

• Name Form:

  lunar collector dev [--pr <pr-number>] [--git-sha <git-sha>] \
    [--component <component-name> | --component-dir <path>] \
    [--fake-ci-cmd <bash-command>] \
    <collector-name>

• Script Form:

  lunar collector dev \
    [--pr <pr-number>] [--git-sha <git-sha>] \
    [--component <component-name> | --component-dir <path>] \
    [--fake-ci-cmd <bash-command>] \
    --script <path-to-collector-script>

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

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

<collector-name>

• Type: string

• Required in Name Form

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

• Type: string

• Required in Script Form

--component <component-name>

• Type: string

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

--component-dir <path>

• Type: string

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

--pr <pr-number>

• Type: integer

• Optional

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

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

# Run collectors in development mode for a component (primary branch)
lunar collector dev --component github.com/my-org/my-repo
# Run collectors in development mode for a specific PR
lunar collector dev --component github.com/my-org/my-repo --pr 123
# Run a specific collector
lunar collector dev --component github.com/my-org/my-repo collector-name
# Run a specific collector script file
lunar collector dev --component github.com/my-org/my-repo --script ./path/to/collector.sh
# Test a CI collector with a fake CI command
lunar collector dev --component github.com/my-org/my-repo --fake-ci-cmd "npm test" ci-collector-name
# Run collectors against a local directory
lunar collector dev --component-dir ./my-local-repo collector-name
# Run collectors against a local directory with a specific git SHA
lunar collector dev --component-dir ./my-local-repo --git-sha abc123 collector-name

Policy Commands

lunar policy ls

Coming Soon — This feature is not yet available.

• Form:

  lunar policy ls

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

lunar policy check ls

Coming Soon — This feature is not yet available.

• Form:

  lunar policy check ls

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

lunar policy run

Coming Soon — This feature is not yet available.

• Form:

  lunar policy run [--output-json] [--pr <pr-number>] \
    [--git-sha <git-sha>] [--policy <policy-name>] \
    [--initiative <initiative-name>] <component-name>

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:

# Rerun policies for a component (primary branch)
lunar policy run github.com/my-org/my-repo
# Rerun policies for a specific PR
lunar policy run --pr 123 github.com/my-org/my-repo
# Rerun policies for a specific git SHA
lunar policy run --git-sha abc123 github.com/my-org/my-repo
# Run only a specific policy
lunar policy run --policy policy-name github.com/my-org/my-repo
# Run policies under a specific initiative
lunar policy run --initiative initiative-name github.com/my-org/my-repo

lunar policy dev

• Name Form:

  lunar policy dev [--component <component-name>] [--component-json <path-to-json-or-stdin>] \
    [--pr <pr-number>] [--git-sha <git-sha>] \
    <policy-name>

• Script Form:

  lunar policy dev [--component <component-name>] [--component-json <path-to-json-or-stdin>] \
    [--pr <pr-number>] [--git-sha <git-sha>] \
    --script <path-to-policy-script>

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

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

<policy-name>

• Type: string

• Required in Name Form

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

• Type: string

• Required in Script Form

--component <component-name>

• Type: string

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

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

• Type: string

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

--pr <pr-number>

• Type: integer

• Optional

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

--git-sha <git-sha>

• Type: string

• Optional

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

--with <args>

• Type: string

• Optional

Arguments passed to the policy script.

--script-lang <language>

• Type: string

• Optional

• Default: python

The script programming language.

--output <format>

• Type: string

• Optional

• Values: json, list

Output format for the policy results.

--config <repo>

• Type: string

• Optional

Remote config repository to use.

--use-system-runtime

• Type: boolean

• Optional

Use the system runtime instead of a containerized environment.

--no-cache

• Type: boolean

• Optional

Disable caching.

--verbose

• Type: boolean

• Optional

Enable verbose output.

--secrets

• Type: boolean

• Optional

Fetch and inject secrets into the policy execution environment.

Example

# Run policy with component JSON from file
lunar policy dev --component-json path/to/component.json --script ./path/to/policy.py
# Run policy by specifying component directly
lunar policy dev --component github.com/my-org/my-repo --script ./path/to/policy.py
# Run policy with component JSON from stdin
lunar component get-json --git-sha ... github.com/my-org/my-repo | \
  lunar policy dev --component-json - --script ./path/to/policy.py
# Run specific policy from config
lunar policy dev --component github.com/my-org/my-repo my-policy
# Run policy for a specific PR
lunar policy dev --component github.com/my-org/my-repo --pr 123 --script ./path/to/policy.py

lunar policy ok-release

• Form:

  lunar policy ok-release <component> <git_sha>
  lunar policy ok-release  # uses LUNAR_COMPONENT_ID and GITHUB_SHA

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.

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

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

--pr <pr-number>

• Type: integer

• Optional

The PR number to check policies for.

lunar policy ok-pr

• Form:

  lunar policy ok-pr <component> <git_sha>
  lunar policy ok-pr  # uses LUNAR_COMPONENT_ID and GITHUB_SHA

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.

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

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

--pr <pr-number>

• Type: integer

• Optional

The PR number to check policies for.

SDK Commands

lunar catalog

Saves catalog-related information from within a cataloger.

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

lunar collect

Collects SDLC metadata from within a collector or external systems.

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:

  lunar sql connection-string

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

Example:

# Get the connection string
lunar sql connection-string
# Connect using psql (interactive)
psql $(lunar sql connection-string)
# Export checks data as CSV
psql $(lunar sql connection-string) -c "COPY (
  SELECT *
  FROM checks
  WHERE component_id = 'github.com/my-org/my-repo'
    AND status = 'fail'
) TO STDOUT WITH CSV HEADER" > failed_checks.csv
# Export component data as JSON
psql $(lunar sql connection-string) -c "
  SELECT json_agg(row_to_json(c))
  FROM (
    SELECT *
    FROM components
    WHERE tags @> '{\"team\":\"ui\"}'
  ) c" > platform_components.json
# Make decisions based on check results
psql $(lunar sql connection-string) -t -c "
  SELECT COUNT(*)
  FROM checks c
  JOIN components comp ON c.component_id = comp.component_id
  WHERE comp.domain = 'payments'
    AND c.status = 'fail'
    AND c.enforcement IN ('block-pr-and-release', 'block-release')" | \
  grep -q "^0$" || \
  (echo "Release blocking checks are failing in payments domain!" && exit 1)

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

lunar secret set

  lunar secret set <name> [value]

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

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

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

Options

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

Examples

# Set a collector secret (value as argument)
lunar secret set GH_TOKEN ghp_abc123

# Set a secret from stdin (recommended)
echo "ghp_abc123" | lunar secret set GH_TOKEN

# Set a policy secret
lunar secret set --scope policy JIRA_API_KEY my-api-key

lunar secret delete

  lunar secret delete <name>

Delete a previously configured secret.

Options

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

Examples

lunar secret delete GH_TOKEN
lunar secret delete --scope policy JIRA_API_KEY

lunar secret list

  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

# List collector secrets
lunar secret list

# List policy secrets
lunar secret list --scope policy

Utility Commands

lunar clear-cache

• Form:

  lunar clear-cache

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:

  lunar version

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