zg CLI reference

Top-level commands#

A global --json flag is available on commands for machine-readable output; the JSON contract is stable within a major version (fields are added, never renamed or removed). Any zg subcommand that is not a zg verb is handed to git unchanged.

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>. It refuses up front when the committed .zegit/config.yaml is not the pipeline the ZEGITFILE pins, and warns when the zg binary was built from a dirty tree (the gateway rejects such release evidence).

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 key
zg validate --trust             # record this repo's pipeline as trusted on this machine
                                # (required when ZEGIT_VALIDATE_REQUIRE_TRUST=1)

Exit codes

zg auth#

Two modes: local IAM (a single-machine simulation, no ZEGIT_CP_URL) and Control-Plane mode (when a CP URL is configured).

zg auth login
zg auth status --json
zg auth enroll --identity jonas@acme --role maintainer
zg auth enroll --canary          # CP mode: a decoy invitation that pages when redeemed

The store is $ZEGIT_HOME, else $XDG_CONFIG_HOME/zegit, else ~/.config/zegit. An optional config.json there sets cp_url and identity; ZEGIT_CP_URL wins when both are set.

zg evidence#

The lower-level evidence pipeline — it mirrors the envelope state machine (unsigned → validated → signed).

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

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

zg policy — release policy as a protected ref#

Once a policy is activated at refs/zegit/policy it — not the tree's ZEGITFILE — decides how releases are gated, and replacing it always needs two distinct owner approvals (the very first activation needs one). The ZEGITFILE stays the proposal source. With ZEGIT_CP_URL set, proposals and approvals are mirrored to the Control Plane's Policy Center; the git ref stays authoritative.

zg aov#

zg aov inspect [<commit>] shows everything an approver or auditor should see for one commit: the decoded record (subject, steps, decision, policy digest, actor, producer), the signer's certificate, the verdict under both clocks, and the tree cross-check. Exits 20 when the commit has no AoV — fetch them first with git fetch gateway 'refs/zegit/aov/*:refs/zegit/aov/*'. zg aov mirror backfills the Control Plane's Attestations page from local AoV refs; it is idempotent and the CP refuses envelopes that do not verify against its trust root.

zg push & zg verify-forward#

zg push <remote> <refspec> pushes with the companion AoV ref in the same transaction, retries a transport that died after the pre-push gate, and verifies the remote ref actually advanced. zg verify-forward <ref> checks the ref reached every forge remote — forwarding from the gateway to GitHub and Gitea is asynchronous.

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. After a Control-Plane login it also writes the wired-clone setup into the clone's own .git/config: a gateway remote using the zegit-gateway: URL prefix and core.sshCommand = zg ssh.

zg init                 # current repo
zg init --repo . --force
zg init --solo          # allow_aov_self_approval: true for a one-person repo
zg init --slug org/repo # registry slug for the gateway remote (default: from origin)

zg git-shim — zg as your git#

Opt-in drop-in: zg git-shim install writes a git shim (default ~/.local/bin/git; put that directory first on PATH). In a governed repo — one with a ZEGITFILE — git push gateway … then validates a commit without an attestation before pushing, and git tag vX.Y.Z (any name matching tag_request.release_tags) opens a Tag Request instead of a local tag. Every other git command is untouched; zg git … is always plain git; zg git-shim status / uninstall report and opt out. Commits are not wrapped — that ceremony stays in hooks.

zg update & zg audit#

zg update installs the latest release from github.com/zegit-zoo/zg after verifying the checksums signature against the Control Plane's artifact key and the archive's sha256 against the checksums (cosign on PATH); --check only reports, --forge gitea --forge-url reads an internal mirror. zg audit verify checks shipped audit-log batches offline — DSSE signature on each batch's Merkle root, root recomputation, intra- and cross-batch chain linkage — from files, an export zip, or straight from an S3 bucket with a read-only key.

zg 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, default validity three years) and prints the key-ceremony next steps; zg ceremony quorum-key generates the Control Plane's quorum-verdict key pair, which every gateway needs to verify tag verdicts; zg ceremony hsm runs the two-custodian YubiHSM ceremony.

zg revert v0.9.0 --message "roll back the bad release"
zg ceremony generate --cn "ZeGit Root CA" --out ./ceremony
zg ceremony quorum-key --out ./ceremony