Generated from the code on main, not from --help alone. Every flag can
also be set by environment variable (GRCLI_ plus the flag name in upper
snake case) or by a key of the same name in the
config file, except where noted. Precedence: flag, then
environment, then config file, then default.
Exit status. grcli exits 0 on success and 1 on any error, printing
grcli: <error> on stderr. There are no other exit codes.
Global flags.
| Flag | Meaning |
|---|---|
--config <file> |
Read this config file instead of ~/.config/grcli/config.yaml. |
-v, --version |
Print the grcli version. |
-h, --help |
Help for any command. |
Commands: validate · publish ·
verify · unpack · cat ·
versions · login · logout
grcli validate -f <file>[,<file>…] [--gemara-version <v> | --spec <dir>]
Scope: General. Checks each file against the Gemara CUE schema with
cue vet. Needs cue on PATH.
| Flag | Default | Meaning |
|---|---|---|
-f, --file |
(required) | Files to check. Repeatable; commas also split. |
--gemara-version |
each file's metadata.gemara-version, else latest |
Check every file against this release (1.6.0, v1.6.0, latest, v1.latest). |
--spec |
(none) | A local checkout of the Gemara CUE module, used instead of the registry. Env: GRCLI_GEMARA_SPEC_DIR. |
For each file grcli:
- Reads
metadata.typeandmetadata.gemara-version.typemust be a bare identifier; anything else fails before cue runs, because it is spliced into the cue expression. - Picks the version:
--gemara-version, else the file's, elselatest. A version must beMAJOR.MINOR.PATCH[-pre],latestorvN.latest. - Prints a warning line (
WARN <file>: …) for each grc.store reference URL that is not in canonical form (see references). - Runs
cue vet -d '#<Type>' github.com/gemaraproj/gemara@v<version> <file>in a fresh temporary directory (so acue.modin your project cannot interfere), orcue vet -d '#<Type>' . <file>inside--spec. Each call times out after 30 seconds.
Output (stdout): cue's own messages, then one line per file:
OK controls.yaml (#ControlCatalog, gemara v1.6.0)
FAIL bad.yaml (#ControlCatalog, gemara v1.6.0): cue vet exited with: exit status 1
With --spec, the label has no version: (#ControlCatalog).
Fails if any file fails (N of M file(s) failed validation), if cue is
missing, or if --spec and --gemara-version are both passed as flags. If
the spec directory comes from the environment or config and a version is
also set there, the spec directory wins and a warning goes to stderr.
grcli publish [<file>…] [-f <file>…] --license <SPDX> [flags]
Scope: Hub protocol, Sigstore; keyless signing is GitHub Actions
only; --dry-run is General.
| Flag | Default | Meaning |
|---|---|---|
-f, --file |
(none) | Input files describing one artifact. Repeatable; commas split. Cannot be combined with positional files. |
--license |
(required) | Publication license, an SPDX expression. Canonicalised and stored as the manifest annotation org.opencontainers.image.licenses. |
--url |
https://hub.grc.store |
Hub base URL. Used for discovery, the version check, registry tokens and the sync. |
--version |
metadata.version |
Written into the packed body's metadata.version and used as the tag. |
--repository |
slugify(author.id)/slugify(id) |
Served repository. The hub rejects a value that disagrees with the metadata (422 catalog_coordinate_mismatch). |
--token |
(none) | Hub bearer token. Env: GRCLI_TOKEN. In Actions, leave unset. |
--cosign-key |
(none) | cosign private key for key-based signing. Env: COSIGN_KEY, cosign's own name for it. Ignored inside GitHub Actions. |
--no-sign |
false |
Do not sign. |
--dry-run |
false |
No network. Write an OCI image layout to --output. |
--output |
grcli-out |
Layout directory for --dry-run. |
Steps, in order (each stops the run on failure):
- Load the files (one artifact;
ControlCatalog/GuidanceCatalogmay merge several files, see source loading). - Apply
--version, printingnote: --version X overrides metadata.version Yon stderr when it changes the value. - Warn on stderr (
warning: …) about non-canonical grc.store reference URLs. - Resolve the target: tag, repository, staging repository
staging/<repository>; unless--dry-run, discover the registry from the hub. - Validate
--license. - Unless
--dry-run:- signing preflight (see signing modes);
GET /v1/catalogs/<ns>/<id>/versions/<v>on the hub:200stops with already exists,410with was yanked;- mint a registry push token for the staging repository (unless
GRCLI_REGISTRY_*is set).
- Build the provenance record and pack the bundle.
- Push to
staging/<ns>/<id>:<version>, or write the layout (--dry-run, which ends here). - Sign the pushed manifest digest.
POST /v1/bundles/syncnaming the served repository and tag.
Publish does not run schema validation; the hub does that at sync.
Output. Dry run (stdout):
dry-run: wrote bundle to oci:grcli-out:0.1.0
manifest digest: sha256:…
body digest: sha256:…
artifact: ControlCatalog/example-controls
Real publish (stdout):
pushed <registry>/staging/<ns>/<id>:<v>
manifest digest: sha256:…
signed (keyless) # or: signed (key) / signing skipped: --no-sign
hub indexed <ns>/<id>:<v> — 1 artifacts (1 new), types=ControlCatalog
With --cosign-key, cosign's own output appears between the pushed and
signed lines.
| Condition | Mode | Needs |
|---|---|---|
--no-sign |
skipped | nothing |
GITHUB_ACTIONS=true |
keyless, in-process | ACTIONS_ID_TOKEN_REQUEST_URL and _TOKEN (from id-token: write) |
otherwise, --cosign-key set |
key, via cosign sign |
cosign 2.6.0 or later |
| otherwise | error: no signing material |
Inside GitHub Actions, keyless wins even if --cosign-key is set.
For the push token and the sync, grcli resolves a hub bearer token in this
order: --token / GRCLI_TOKEN / a token: config key; then, inside
GitHub Actions, a fresh OIDC token for the hub's advertised ci_audience
(falling back to the --url value); then the stored grcli login
credentials for the hub's OIDC issuer, refreshed if expired.
grcli verify --repository <ns>/<id> --version <v> [trust flags]
Scope: Hub protocol (discovery always; signer lookup in zero-flag mode), Sigstore.
| Flag | Default | Meaning |
|---|---|---|
--repository |
(required) | <ns>/<id>. |
--version |
(required) | The version (tag). |
--url |
https://hub.grc.store |
Hub, for discovery and the signer lookup. |
--certificate-identity |
(none) | Exact expected certificate subject (SAN). Selects explicit keyless mode. |
--certificate-oidc-issuer |
GitHub Actions issuer, in explicit keyless mode | Expected OIDC issuer. Requires --certificate-identity. |
--cosign-key |
(none) | cosign public key. Selects key mode. Exclusive with the two flags above. |
(config/env only) trusted-root / GRCLI_TRUSTED_ROOT |
embedded root | Path to a trusted_root.json. |
Modes:
| Mode | Selected by | Identity checked | Runs |
|---|---|---|---|
| Zero-flag | no trust flags | the hub's recorded signer for <ns>/<id>: issuer exact, SAN matching ^<workflow-path>@ (any ref) |
in-process |
| Explicit keyless | --certificate-identity |
SAN exact, issuer exact | in-process |
| Key | --cosign-key |
the key | cosign verify |
In-process verification requires a Rekor entry, an observed timestamp and an
SCT, against the embedded Sigstore public-good trust root (from
grc-store-clientkit/trustroot) or GRCLI_TRUSTED_ROOT.
Output (stdout):
verifying <registry>/<ns>/<id>:<v> (keyless identity from hub record: <identity>, issuer <issuer>)
verified: keyless:<issuer>#<workflow-path>
The first line's parenthesis reads keyless identity=<SAN> issuer=<issuer>
in explicit mode and key=<path> in key mode. Key mode prints cosign's
output instead of the verified: line.
Verify does not support a local layout: a signature exists only in a registry.
grcli unpack --repository <ns>/<id> --version <v> [flags]
grcli unpack --source <layout-dir> --version <v> [flags]
Scope: Hub protocol with --url; General with --source.
| Flag | Default | Meaning |
|---|---|---|
--version |
(required) | Version (tag). |
--repository |
(required with --url) |
<ns>/<id>. |
--url |
https://hub.grc.store |
Hub. Ignored when --source is given and --url is not. |
--source |
(none) | OCI image layout directory. Exclusive with an explicit --url. |
--output |
grcli-unpacked |
Directory to write into. |
--no-verify |
false |
Skip signature verification (warns). |
--certificate-identity, --certificate-oidc-issuer |
(none) | As for verify; replaces the hub lookup. |
--with-imports |
false |
Also pull references targeted by imports. |
--with-references |
false |
Also pull every mapping reference. Wins over --with-imports. |
--no-cache |
false |
Do not read or write the cache this run. |
Steps:
- Fetch the bundle (cache first, then registry; see cache).
- Verify the signature as
verifydoes (zero-flag or explicit keyless; key mode is not offered), unless--no-verifyor--source. On failure, nothing is written and the output directory is not created. - Write the artifact file and
bundle.jsonto--output. File names that would escape the directory are refused. - With
--with-*, resolve references (see references).
Output (stdout):
verifying signature (keyless identity from hub record: …)
verified: keyless:…
unpacked <hub-host>/<ns>/<id>:<v> → grcli-unpacked (1 files, 0 imports)
- controls.yaml
- bundle.json (bundle manifest)
Reference resolution adds lines such as - skip [reference] <url>: <reason>,
! license: … — review before reuse, - references/index.json and
resolved N reference(s), skipped M.
grcli cat --repository <ns>/<id> --version <v> [--file <name>]
grcli cat --source <layout-dir> --version <v> [--file <name>]
Scope: as unpack.
| Flag | Default | Meaning |
|---|---|---|
--version, --repository, --url, --source, --no-cache |
As for unpack. |
|
--file |
(none) | Fail unless the artifact's file name is this. Read from the command line only, never from env or config. |
Writes the artifact's bytes to stdout, unchanged. Never writes
bundle.json, never verifies the signature, never resolves references.
Cache diagnostics and a note about omitted imports go to stderr.
grcli versions <ns>/<id> [--latest]
Alias: releases. Scope: Hub protocol. No login needed.
| Flag | Default | Meaning |
|---|---|---|
--url |
https://hub.grc.store |
Hub. |
--latest |
false |
Print only the latest version. |
Calls GET /v1/catalogs/<ns>/<id>. Output:
VERSION PUSHED DIGEST
1.1.0 (latest) 2026-07-06T02:27:18.361705Z sha256:b87a3a61f910
1.0.0 2026-06-22T13:06:34.340457Z sha256:2e7f2af8d942
Rows are in the hub's order (newest first); digests are shortened to 12 hex
characters. --latest prints one bare version, or nothing (exit 0) if the
catalog has no releases. Without --latest, no releases is an error.
catalog not found and catalog was yanked are errors.
grcli login [--url <hub>]
Scope: Hub protocol (the hub must advertise oidc_issuer and
oidc_cli_client_id).
Runs the OAuth 2.0 device authorization grant (RFC 8628) against the hub's OIDC issuer and stores the access and refresh tokens. Output:
Discovering https://hub.grc.store ...
Open this URL in any browser to authorize:
https://auth.grc.store/realms/…/device?user_code=ABCD-EFGH
Or visit https://auth.grc.store/realms/…/device and enter code: ABCD-EFGH
(code expires in 10m0s)
Waiting for authorization...
✓ Signed in to https://auth.grc.store/realms/…
Token stored at ~/.local/share/grcli/credentials.json (expires 2026-…)
Credentials are keyed by issuer; logging in again replaces them.
grcli logout [--url <hub> | --issuer <issuer-url>]
Scope: Hub protocol with --url; local only with --issuer.
Deletes the stored credentials for the hub's issuer. Does not contact the
issuer or revoke anything. Pass --issuer when the hub is unreachable.
Output: ✓ Forgot credentials for <issuer>.