These docs describe grcli as the code on main behaves, not as it was meant to
behave. Where the two differ, the docs say so. They follow the
Diátaxis layout: four kinds of page, each for a
different need.
| You want to… | Read |
|---|---|
| Learn grcli by doing, start to finish | Tutorials |
| Get one specific job done | How-to guides |
| Look up a command, flag, setting or file format | Reference |
| Understand how grcli works and why it is built this way | Explanation |
- Your first bundle, offline: write a Gemara catalog, validate it, pack it, and read it back, with no account and no network beyond the schema download.
- Publish from GitHub Actions: take the same catalog to a hub through trusted publishing, then verify and unpack what you published.
- Install grcli and check its signature
- Publish an artifact
- Verify an artifact before you trust it
- Fetch an artifact and the artifacts it references
- Point grcli at another hub, registry or Sigstore
- Fix a failed publish
- Commands: every command and flag, what it prints, and when it fails.
- Configuration and environment: the config
file, every
GRCLI_*variable, and the files grcli reads and writes. - Formats and protocol: the hub
endpoints grcli calls, the bundle layout, the provenance record, the
signature, the cache, and
references/index.json.
- Architecture: the packages, the data flow of each command, and what grcli depends on.
- Signing and verification: what is signed, by whom, and what each verify mode trusts.
- Design decisions: why grcli works the way it does, decision by decision.
- What is general and what is grc.store-specific: which parts of grcli would work against something other than a grc.store hub, and which would not.
- Known gaps and surprises: behaviour that is undocumented elsewhere, dead, or likely to surprise a maintainer.
Pages mark how far each behaviour reaches with these labels:
| Label | Means |
|---|---|
| General | Works with any Gemara file or any OCI registry. No hub needed. |
| Hub protocol | Needs a server that speaks the grc.store hub protocol (discovery document, /v2/token, /v1/bundles/sync, /v1/catalogs). The grc.store hub is the only implementation today. |
| grc.store | Hard-wired to the public grc.store deployment: a default URL, a host name, a URI. |
| GitHub Actions | Assumes GitHub Actions is the CI system and its OIDC token is the identity. |
| Sigstore | Assumes Sigstore (Fulcio and Rekor), by default the public-good instance. |
- Gemara: the YAML format grcli publishes. Each file is one artifact
(a control catalog, a threat catalog, a policy, an evaluation log, and so
on) with a
metadatablock that names itstype,id,version,authorandgemara-version. - Bundle: one artifact packed as an OCI image manifest, with a
bundle.jsonmanifest that carries the provenance record. Built by thebundlepackage of go-gemara. - Hub: the server that indexes published bundles, mints registry tokens
and decides who may publish where. grc.store runs one at
hub.grc.store. - Coordinate:
<namespace>/<id>@<version>. It names one published version. The namespace is the publisher's account on the hub. - Staging repository:
staging/<namespace>/<id>, where grcli pushes a bundle before the hub checks it and copies it into the served repository<namespace>/<id>.