Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/dev/llms.txt
Full corpus: https://docs.registrystack.org/dev/llms-full.txt

# Evidencectl command reference

> Reference for Evidence Gateway authoring, production build, deployment inspection, fixture, and local-development commands.

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

## Related reference

- [Configure Evidence Gateway](../../configure/evidence/)
- [Registry Mint reference](../mint/)
- [Build and deploy an Evidence Gateway project](../../tutorials/build-and-deploy-evidence-project/)