Evidencectl command reference

View as Markdown

evidencectl is Evidence Gateway adopter tooling. It creates key material and editable projects, compiles production candidates, and invokes the evidence binary for Evidence Gateway semantic decisions. It does not approve, deploy, promote, register production clients, or write production secret values. Its client registration commands manage local development only.

Contract status

Evidencectl is outside the frozen Evidence Gateway Version 1 runtime contract. Its command line can change before a compatibility promise covers it. The evidence runtime remains the authority for bundle compilation, fixture evaluation, secret validation, and startup acceptance.

Production build commands

Command	Inputs	Result	Does not do
`evidencectl build --project <project> --target <target> --output <new-candidate>`	Editable project and one explicit production target	Creates a new candidate with `runtime.yaml` and closed `bundle/`	Overwrite output, contact source services, OIDC, or Mint, create production secrets, or start a listener
`evidencectl doctor --project <candidate>`	Completed candidate on its target host	Reports runtime, bundle, secret, and audit file posture	Change project files or replace `evidence check`
`evidencectl doctor --project <candidate> --mint-config <mint.yaml>`	Completed candidate and separately authored Mint configuration	Adds read-only mechanical protocol compatibility checks	Register callers, copy Mint files, infer authority, or mint a token
`evidencectl fixtures run --project <candidate>`	Completed candidate and referenced synthetic fixtures	Runs `evidence check` and every referenced fixture	Start HTTP, call a source, or write a production audit entry
`evidencectl fixtures run --project <candidate> --explain`	The same, and asks each evaluation to explain itself	Relays each fixture’s stage trace beside its step, or as that fixture’s `trace` field under `--json`	Print a response, fact, derived, or selector value, or explain a served request

build is create-only. It rejects an existing output directory, local assurance inputs, unauthenticated or non-HTTPS production sources, missing governance metadata or fixtures, unresolved review markers, unknown fields, symlink traversal, and references outside the allowed project directories. A failed build publishes no candidate.

Production input reference

An editable project becomes a production build input only after it has:

A fixtures/ regular file referenced by every production question.
Stable concept identifiers and production governance metadata in every question.
environments/<target>/evidence/governance.yaml with bundle-owned fields for one environment.
environments/<target>/evidence/runtime.yaml with one environment’s runtime bindings.
environments/<target>/evidence/public-keys/ with every active and published service JWK.

governance.yaml is strict. It must carry version 1, assuranceProfile: production, service, issuer, authentication, audit, subject binding, rate limits, signing, optional response formats, and authority profiles. It cannot supply selector profiles, sources, or requirements. It accepts logical secret:file/<name> references, not values or absolute secret paths.

The output runtime document is copied byte-for-byte. Its paths and secret posture are accepted only by the final target-host evidence check.

Keep the editable project under shared/evidence-project/ and each complete deployment target under environments/<target>/evidence/. Do not use overlays, environment branches, symlinks, or runtime substitutions. Git contains public keys and nonsecret provider configuration, but no private JWKs, HMAC keys, provider tokens, auto-auth credentials, access tokens, live responses, or real identifiers.

Local-only commands

evidencectl new --profile local and evidencectl dev are local-authoring commands. Nothing under .evidence/dev is a production build input. new creates no source policy, question, fixture content, production target, Mint configuration, or deployable bundle. It automatically creates disposable, unbound Evidence Gateway key material in the ignored owner-only secrets/ directory. dev creates session-scoped P-256 pairs for Registry Mint, the local caller, and the optional SD-JWT VC holder. None of those keys enters a production target.

evidencectl access manages caller access for one local project:

Command	State	Result
`evidencectl access policy add <policy> --question <question>`	Creates `access/policies/<policy>.yaml`	Defines one or more repeated `--question` values for the next Evidence Gateway generation
`evidencectl access policy list`	Reads `access/policies/`	Lists the governed local policies and their questions
`evidencectl access client add <client> --policy <policy> --generate-local-key`	Creates `access/clients/<client>.yaml` and `.evidence/clients/<client>/private.jwk`	Registers a local client for repeated `--policy` values with non-overlapping question sets
`evidencectl access client list`	Reads `access/clients/`	Lists local client status and policy membership
`evidencectl access client revoke <client>`	Updates `access/clients/<client>.yaml`	Revokes the local client for new token requests

Public, reviewable local access configuration lives under access/. Owner-only private client keys live only under .evidence/clients/. Generated Registry Mint registrations under .evidence/dev/generated/clients/ are disposable and contain public keys only.

Client add and revoke request a Registry Mint reload only when evidencectl dev has a ready local session. They do not restart or reload Evidence Gateway. Registry Mint does not acknowledge completion of the reload, so the next token exchange provides the functional check. A policy change requires a new Evidence Gateway generation.

The local access commands do not define production authority or production clients. Production authority profiles remain in the deployment target’s governed governance.yaml. Production client registrations remain in a separately governed Registry Mint registry. Files under access/ and .evidence/ do not become production candidate inputs.

Use keygen, source suggest, request, verify, and audit for their documented authoring or local inspection roles. Do not use a local request, local audit record, or disposable key as a production candidate input.