● zegit · proves
zg CLI reference
The complete zg command surface — the developer and agent-facing CLI. Documented from the source, not the design prose.
Code is authoritative
Where product/architecture documents describe a richer design than what ships (for example a zg build command), this reference follows what the binary actually does today.
Top-level commands
| Command | Description |
|---|---|
zg version | Show version, commit, build time. |
zg init | Bootstrap a repo: .zegit/config.yaml, ZEGITFILE, and the pre-push hook. |
zg auth | Local IAM / Control-Plane auth: enroll, login, status, certs, automation. |
zg validate | Run the pipeline, assemble an AoV, evaluate policy, sign into refs/zegit/aov/<sha>. |
zg evidence | Evidence record ops: evaluate, keygen, sign, verify, bundle, verify-bundle, verify-aov. |
zg tr | Tag Requests with quorum: create, list, get, approve, finalize. |
zg revert | Owner-only break-glass revert to a safe tag. |
zg ceremony | CA key ceremony — generate the ZeGit Root CA. |
A global --json flag is available on commands for machine-readable output.
zg validate
The core loop. Resolves HEAD's commit and tree, loads .zegit/config.yaml, runs each step with a streaming transcript, computes a policy digest over .zegit/config.yaml + ZEGITFILE, assembles the record, evaluates policy, and — unless blocked — signs a DSSE AoV to refs/zegit/aov/<commit>.
zg validate # sign an AoV for HEAD
zg validate --risk review # set the risk policy: allow | review | block
zg validate --no-sign --json # evaluate only; print the decision
zg validate --key dev.key # sign with an explicit keyExit codes
| Code | Meaning |
|---|---|
0 | ALLOW |
10 | REQUIRE_REVIEW |
20 | BLOCK (a required step failed, or risk blocks) |
1 / 2 | IO/exec error / usage error |
zg auth
Two modes: local IAM (a single-machine simulation, no ZEGIT_CP_URL) and Control-Plane mode (when a CP URL is configured).
| Subcommand | Description |
|---|---|
auth init-ca | Create a local CA root (ca/root.crt, ca/root.key). |
auth enroll | Enroll a passkey and record an identity + role. |
auth login | WebAuthn ceremony → a short-lived leaf cert at cert/cert.pem. |
auth status | Show the current cert: identity, role, expiry. |
auth ssh-cert | Fetch a gateway SSH user certificate for the current session. |
auth automation-keygen | Generate an ed25519 automation keypair. |
auth automation-register | Owner registers an automation pubkey at the CP. |
auth automation-login | Passwordless cert issuance for agents (challenge → sign → login). |
zg auth login
zg auth status --json
zg auth enroll --identity jonas@acme --role maintainerLogin cert validity scales with role
Default login cert lifetimes are developer 8h, maintainer 1h, owner 5m — the more privilege, the more often you touch the passkey.
zg evidence
The lower-level evidence pipeline — it mirrors the envelope state machine (unsigned → validated → signed).
| Subcommand | Description |
|---|---|
evidence evaluate | Evaluate a record against the policy engine; --stamp writes a validated envelope. |
evidence keygen | Generate an ed25519 keypair (PKCS#8 + PKIX PEM); prints a key_id. |
evidence sign | Sign an evaluated record into a DSSE envelope. |
evidence verify | Verify a signed AoV DSSE envelope. |
evidence bundle | Assemble a CRA Evidence Bundle for a release tag. |
evidence verify-bundle | Verify a bundle offline against a Root CA. |
evidence verify-aov | Verify the AoV at refs/zegit/aov/<commit> against a CA root. |
zg evidence keygen --out .zegit/keys/dev
zg evidence evaluate run.jsonl --stamp validated.jsonl --risk allow
zg evidence sign validated.jsonl --key .zegit/keys/dev.key --out aov.dsse
zg evidence verify aov.dsse --key .zegit/keys/dev.pubSee CRA & compliance for the bundle commands in context.
zg tr — Tag Requests
The human-in-the-loop release gate. TR refs live at refs/zegit/tr/<tag>; approvals at refs/zegit/tr/<tag>/approvals/<keyid>.
| Subcommand | Description |
|---|---|
tr create <tag> | Open a TR at a commit (default HEAD); threshold/roles from ZEGITFILE. |
tr list | List open TRs and their quorum status. |
tr get <tag> | Show a TR, its approvals, and quorum. |
tr approve <tag> | Approve with a fresh passkey touch. |
tr finalize <tag> | Create the signed annotated tag once quorum is met. |
The creator can't self-approve
The creator's own approval never counts toward quorum unless the repo sets allow_aov_self_approval: true. zg tr finalize exits 30 (ZG_ERR_QUORUM_NOT_MET) if quorum isn't met.
zg init
Bootstraps a repo and installs a guarded pre-push hook. The hook pushes refs/zegit/aov/*, and for each refs/tags/v* being pushed it verifies a matching TR ref exists (else aborts) and pushes it first. Idempotent and composes with an existing hook.
zg init # current repo
zg init --repo . --forcezg revert & zg ceremony
zg revert <tag> is an owner-only break-glass: it restores the tree to a safe tag, requires a passkey touch, signs an AoV, and resets HEAD. zg ceremony generate produces the ZeGit Root CA (root.crt + root.key) and prints the key-ceremony next steps.
zg revert v0.9.0 --message "roll back the bad release"
zg ceremony generate --cn "ZeGit Root CA" --out ./ceremonyAuthoritative reference, generated from the component repos. Spot something stale? Tell us.