Docs

CLI reference

CLI reference

The govai command is shipped with the aigov-py Python package in this repository (python/pyproject.toml, implementation python/aigov_py/cli.py). Install from PyPI (pin the version in CI to match your action pin):

python -m pip install "aigov-py==0.2.1"

Run govai --help and govai <command> --help for the exact flags for your installed version.

CLI command catalog

Search commands — click copy to use in your terminal.

govai

CI gates

Commands used in release and compliance pipelines.

3
  • govai checkGET /compliance-summary — exit 0 only on VALID.
  • govai verify-evidence-packDigest + optional export cross-check against hosted ledger.
  • govai submit-evidence-packReplay CI evidence JSON to POST /evidence.

Evidence packs

2
  • govai evidence-pack initStarter run JSON + digest manifest.
  • govai preflightLocal validation before submit.

Read APIs via CLI

2
  • govai compliance-summaryPrint authoritative verdict JSON.
  • govai export-runExport run artefacts for audit review.

Global flags (root parser)#

FlagEnv / configPurpose
--version / -V—Print package version and exit.
--config.govai/config.json or GOVAI_CONFIGPath to JSON config.
--audit-base-urlGOVAI_AUDIT_BASE_URL (and config)Audit HTTP base URL.
--api-keyGOVAI_API_KEY (and config)Bearer token for gated audit routes.
--projectGOVAI_PROJECT / X_GOVAI_PROJECTSets X-GovAI-Project header (metadata only; does not select tenant).
--timeoutGOVAI_TIMEOUT_SEC (default 30)HTTP timeout in seconds.
--compact-json—Single-line JSON for selected commands (for example compliance-summary).

Exit codes (python/aigov_py/cli_exit.py)#

CodeConstantMeaning
0EX_OKSuccess. For govai check / verify-evidence-pack, success implies VALID verdict when checking verdict.
1EX_ERRTransport, HTTP failure, parse failure, digest/export mismatch, or unexpected error.
2EX_INVALIDCompliance verdict INVALID.
3EX_BLOCKEDCompliance verdict BLOCKED.
4EX_USAGECLI usage error (including argparse errors).

Note: govai check help text documents exit 4 as “usage”; infrastructure failures use exit 1 (see parser docstrings in cli.py).

govai check#

Queries GET /compliance-summary for the run and exits 0 only if the verdict is VALID.

  • Positional or --run-id: run UUID (also GOVAI_RUN_ID / RUN_ID).
  • --verify-artifacts <dir>: After verdict check, require evidence_digest_manifest.json under dir to match hosted GET /bundle-hash (artefact continuity).

Does not alone prove full CI artefact binding; for release gates prefer verify-evidence-pack (and the composite GitHub Action). See github-action.md.

govai verify-evidence-pack#

Hosted gate for CI artefacts:

  • Requires --path <dir> with evidence_digest_manifest.json and <run_id>.json.
  • Compares manifest digest to hosted GET /bundle-hash (events_content_sha256).
  • --require-export: fail if GET /api/export/:run_id cross-check cannot be performed or disagrees with /bundle-hash.
  • --artifact-file: optional on-disk promoted model file; verifies SHA256 against bundle payload when provided.

Evidence pack generation#

CommandPurpose
govai evidence-pack initWrites <run_id>.json and evidence_digest_manifest.json under --out (default evidence_pack/). --run-id optional (CI-deterministic on GitHub Actions; else UUID). --force to overwrite.

Related:

  • govai submit-evidence-pack — POST every event from <dir>/<run_id>.json to POST /evidence.
  • govai preflight — Local validation and optional --with-submit against the audit service (see --help).

Report generation#

CommandPurpose
govai reportRenders docs/reports/<run_id>.md from evidence / bundle inputs (see govai report --help).

Other documented customer paths (non-exhaustive)#

The CLI exposes additional subcommands (init, export-run, compliance-summary, usage, discovery, policy, standards, …). Only document commands you use; this page lists those explicitly tied to public docs and CI gates in this repository.

CI integration#

  • Composite action and pins: github-action.md
  • Artefact-bound gate: submit-evidence-pack then verify-evidence-pack with --require-export by default in the published action.

← Back to home