> For the complete documentation index, see [llms.txt](https://docs-lunar.earthly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-lunar.earthly.dev/docs/lunar-cli.md). # Lunar CLI Reference This document provides a comprehensive reference for all available options and commands in the Lunar CLI. ## Global options ### `--config-dir `, `LUNAR_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 `, `LUNAR_HUB_HOST=` * 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 `, `LUNAR_HUB_GRPC_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 `, `LUNAR_HUB_HTTP_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 `, `LUNAR_LICENCE_FILE=` * 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: ```bash lunar licence verify --licence-file ``` 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: ```bash lunar licence pull-secret --licence-file --namespace [--name ] [--out ] ``` 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 ` | `-n` * Type: `string` * Required Kubernetes namespace for the Secret. #### `--name ` * Type: `string` * Optional * Default: `regcred` Kubernetes Secret name. The Hub chart's `imagePullSecrets` reference defaults to `regcred`. #### `--out ` | `-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 ```bash # 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: ```bash lunar licence registry-token --licence-file ``` 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: ```bash 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: ```bash lunar hub pull [--rerun-code-collectors|-l] [--include-pr-commits] [--pr-max-age-days ] [--rerun-catalogers|-t] ``` 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](/install/github-actions.md) is a thin wrapper around this command and exposes the same flags as inputs. {% hint style="warning" %} 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. {% endhint %} #### `` * Type: `string` * Form: `github:///@` * 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 ` * 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: ```bash lunar hub run-code-collectors [--pr-max-age-days ] [--include-pr-commits] ``` The `lunar hub run-code-collectors` command instructs Lunar Hub to rerun code collectors. {% hint style="warning" %} 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. {% endhint %} #### `--pr-max-age-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: ```bash lunar hub get-logs [--namespace ] [--output ] [--tail ] ``` The `lunar hub get-logs` command retrieves logs from Lunar Hub. #### `--namespace ` | `-n` * Type: `string` * Optional The Kubernetes namespace to retrieve logs from. #### `--output ` | `-o` * Type: `string` * Optional Output format for the logs. #### `--tail ` * Type: `integer` * Optional Number of lines to show from the end of the logs. ## Domain Commands ### `lunar domain ls` {% hint style="info" %} **Coming Soon** — This feature is not yet available. {% endhint %} * Form: ```bash lunar domain ls ``` The `lunar domain ls` command is used to list all domains. ## Component Commands ### `lunar component ls` {% hint style="info" %} **Coming Soon** — This feature is not yet available. {% endhint %} * Form: ```bash lunar component ls ``` The `lunar component ls` command is used to list all components. ### `lunar component get-json` * Form: ```bash lunar component get-json [--git-sha ] [--pr ] [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 ` * Type: `string` * Optional The specific git SHA to retrieve the component JSON for. If not specified, the latest component JSON will be retrieved. #### `--pr ` * 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: ```bash 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: ```bash lunar cataloger get-json [--cataloger ] [--component ] [--ts ] [--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 ` * 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 ` * 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 ` * 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: ```bash # 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: ```bash lunar cataloger run [--cataloger ] [--component ] [--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 ` * 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 ` * 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: ```bash lunar cataloger run --cataloger sbom --component github.com/my-org/my-repo --output-json ``` ### `lunar cataloger dev` * Form: ```bash lunar cataloger dev [cataloger-name] \ [--component | --component-dir ] \ [--config ] \ [--git-sha ] \ [--script ] [--script-lang ] \ [--use-system-runtime] [--no-cache] [--verbose] \ [--secrets ] \ [--output-json] ``` {% hint style="warning" %} Catalogers can be highly environment-dependent. Be mindful of "works on my machine" types of issues. {% endhint %} 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 ` * 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 ` * Type: `string` * Optional Treat the given local directory as the component checkout (no clone). Mutually exclusive with `--component` and `--config`. #### `--config ` * 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 ` * 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. {% hint style="info" %} Unlike `lunar collector dev`, there is no `--pr` flag — catalogers run on pushes to main, not on PR commits. {% endhint %} #### `--script ` * 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 ` * 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 ` * 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](/docs/catalog-json.md). Without this flag, each cataloger's raw emitted JSON is printed under a per-cataloger header. Example: ```bash lunar cataloger dev sbom --component github.com/my-org/my-repo --verbose ``` ## Collector Commands ### `lunar collector run` {% hint style="info" %} **Coming Soon** — This feature is not yet available. {% endhint %} * Form: ```bash lunar collector run [--output-json] [--pr ] \ [--git-sha ] [--only-code] [--only-cron] \ [--collector ] [--pr-max-age-days ] ``` 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. #### `` * Type: `string` The name of the component to rerun collectors for. #### `--pr ` * 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 ` * 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 ` * Type: `string` * Optional * Repeatable Run only the specified collector. This flag can be repeated to run multiple specific collectors. #### `--pr-max-age-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: ```bash # 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: ```bash lunar collector dev [--pr ] [--git-sha ] \ [--component | --component-dir ] \ [--fake-ci-cmd ] \ ``` * Script Form: ```bash lunar collector dev \ [--pr ] [--git-sha ] \ [--component | --component-dir ] \ [--fake-ci-cmd ] \ --script ``` {% hint style="warning" %} Collectors can be highly environment-dependent. Be mindful of "works on my machine" types of issues. {% endhint %} 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. #### `` * Type: `string` * Required in Name Form #### `--script ` * Type: `string` * Required in Script Form #### `--component ` * 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 ` * 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 ` * 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 ` * Type: `string` * Optional The specific git SHA to run collectors for. If specified, this takes precedence over `--pr`. #### `` * 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 ` * 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 ` * 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 ```bash # 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` {% hint style="info" %} **Coming Soon** — This feature is not yet available. {% endhint %} * Form: ```bash lunar policy ls ``` The `lunar policy ls` command is used to list all policies. ### `lunar policy check ls` {% hint style="info" %} **Coming Soon** — This feature is not yet available. {% endhint %} * Form: ```bash lunar policy check ls ``` The `lunar policy check ls` command is used to list all checks. ### `lunar policy run` {% hint style="info" %} **Coming Soon** — This feature is not yet available. {% endhint %} * Form: ```bash lunar policy run [--output-json] [--pr ] \ [--git-sha ] [--policy ] \ [--initiative ] ``` 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. #### `` * Type: `string` The name of the component to rerun policies for. #### `--pr ` * 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 ` * Type: `string` * Optional The specific git SHA to rerun policies for. If specified, this takes precedence over `--pr`. #### `--policy ` * Type: `string` * Optional * Repeatable Run only the specified policy. This flag can be repeated to run multiple specific policies. #### `--initiative ` * 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: ```bash # 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: ```bash lunar policy dev [--component ] [--component-json ] \ [--pr ] [--git-sha ] \ ``` * Script Form: ```bash lunar policy dev [--component ] [--component-json ] \ [--pr ] [--git-sha ] \ --script ``` {% hint style="warning" %} Policies can be highly environment-dependent. Be mindful of "works on my machine" types of issues. {% endhint %} 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. #### `` * Type: `string` * Required in Name Form #### `--script ` * Type: `string` * Required in Script Form #### `--component ` * 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 ` * Type: `string` The path to the component JSON file or `-` to read from stdin. #### `--pr ` * 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 ` * Type: `string` * Optional The specific git SHA to run the policy against. If specified, this takes precedence over `--pr`. #### `--with ` * Type: `string` * Optional Arguments passed to the policy script. #### `--script-lang ` * Type: `string` * Optional * Default: `python` The script programming language. #### `--output ` * Type: `string` * Optional * Values: `json`, `list` Output format for the policy results. #### `--config ` * 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 ```bash # 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: ```bash lunar policy ok-release 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. #### `` * Type: `string` The name of the component to check. Falls back to the `LUNAR_COMPONENT_ID` environment variable when no arguments are given. #### `` * Type: `string` The git SHA to check. Falls back to the `GITHUB_SHA` environment variable when no arguments are given. #### `--poll-interval ` * Type: `duration` * Optional * Default: `10s` How often to poll for results. #### `--timeout ` * Type: `duration` * Optional * Default: `10m` Maximum time to wait for results before timing out. #### `--workflow-id ` * Type: `string` * Optional The CI workflow ID to associate with the check. #### `--pr ` * Type: `integer` * Optional The PR number to check policies for. ### `lunar policy ok-pr` * Form: ```bash lunar policy ok-pr 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. #### `` * Type: `string` The name of the component to check. Falls back to the `LUNAR_COMPONENT_ID` environment variable when no arguments are given. #### `` * Type: `string` The git SHA to check. Falls back to the `GITHUB_SHA` environment variable when no arguments are given. #### `--poll-interval ` * Type: `duration` * Optional * Default: `10s` How often to poll for results. #### `--timeout ` * Type: `duration` * Optional * Default: `10m` Maximum time to wait for results before timing out. #### `--workflow-id ` * Type: `string` * Optional The CI workflow ID to associate with the check. #### `--pr ` * 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](/plugin-sdks/bash-sdk/cataloger.md) page. ### `lunar collect` Collects SDLC metadata into a component's JSON. Pass `--component` and `--sha` to collect against a specific component and commit from anywhere. For detailed documentation on the `lunar collect` command and all its options, see the [Collector Bash SDK](/plugin-sdks/bash-sdk/collector.md) page. ## SQL Commands ### `lunar sql connection-string` * Form: ```bash 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](/sql-api/sql-api.md) documentation. Example: ```bash # 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](/sql-api/sql-api.md) documentation. ### `lunar secret set` ```bash lunar secret set [value] ``` Set a secret that will be available to collectors, policies, or catalogers as `LUNAR_SECRET_`. 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 ` — Secret scope: `collector` (default), `policy`, or `cataloger`. #### Examples ```bash # 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` ```bash lunar secret delete ``` Delete a previously configured secret. #### Options * `--scope ` — Secret scope: `collector` (default), `policy`, or `cataloger`. #### Examples ```bash lunar secret delete GH_TOKEN lunar secret delete --scope policy JIRA_API_KEY ``` ### `lunar secret list` ```bash lunar secret list ``` List the names of configured secrets for a given scope. Values are never displayed. #### Options * `--scope ` — Secret scope: `collector` (default), `policy`, or `cataloger`. #### Examples ```bash # List collector secrets lunar secret list # List policy secrets lunar secret list --scope policy ``` ## Utility Commands ### `lunar clear-cache` * Form: ```bash 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: ```bash lunar version ``` The `lunar version` command prints the Lunar CLI version and commit SHA. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs-lunar.earthly.dev/docs/lunar-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.