CLI overview

The trustplane CLI is how you drive TrustPlane Auth from your terminal: generate keys, mint short-lived passports, sign proof-bound requests, and author trust bundles — all locally, without standing up any infrastructure first. cmd/trustplane-cli builds the trustplane binary, the CLI for TrustPlane Auth.

Install the CLI

The CLI is versioned. The current release is v0.2.4; enrollment (trustplane enroll) requires v0.2.1 or later — the v0.1.x releases did not include it. v0.2.4 archives are published per platform as trustplane_v0.2.4_<os>_<arch>.tar.gz (darwin/linux, amd64/arm64) alongside a SHA256SUMS file and a machine-readable release-manifest.json on the downloads mirror; verifying SHA256SUMS before running any downloaded binary is mandatory. See Install & artifacts.

The current adapter container image tag is v0.2.2 (ghcr.io/trustplane-dev/trustplane-auth-adapter:v0.2.2, public on GHCR); pin the digest shown on the package page. The Helm OCI chart is published at 0.2.2; a broker container image is not part of the current release (the broker runs from source builds and the local demo).

From a TrustPlane Auth source tree:

make build      # produces ./bin/trustplane (+ adapter + broker)

Optionally put it on your PATH:

export PATH="$PWD/bin:$PATH"
trustplane --help

The historical v0.1 local command set (v0.1.x releases; exactly these)

The v0.1.x releases shipped exactly this local command set — without enroll:

trustplane gen-key
trustplane issue
trustplane sign
trustplane verify
trustplane bundle build
trustplane bundle merge-source
trustplane bundle remove-source
trustplane bundle sign
trustplane bundle verify
trustplane broker issue
trustplane up
trustplane demo

Deliberately excluded from the v0.1 local boundary

The v0.1 local boundary excludes onboard, list-keys, blindfold, gateway-call, and cloud instance-identity proof flows, plus managed administration and bundle distribution. See v0.1 boundary.

Current command set (v0.2.4)

trustplane enroll was added in v0.2.1; the current signed release tag is v0.2.2. The v0.2.4 top-level commands are:

trustplane gen-key
trustplane issue
trustplane sign
trustplane enroll
trustplane verify
trustplane bundle build
trustplane bundle merge-source
trustplane bundle remove-source
trustplane bundle sign
trustplane bundle verify
trustplane auth-plane
trustplane broker
trustplane up
trustplane demo

enroll requires v0.2.1 or later

trustplane enroll performs Control Trust Anchor enrollment — it was excluded at the v0.1 local boundary, so older pages listing it as excluded do not apply to that flow on v0.2.1+. See OIDC JWKS enrollment runbook.

Commands

gen-key

Generate a signing key pair for local issuing/signing.

issue

Mint a short-lived passport (and optionally write a trust bundle with the public key).

trustplane issue \
  --subject spiffe://example.local/ns/default/sa/demo \
  --audience example-api \
  --trust-domain example.local \
  --bundle-out trustplane-bundle.json

sign

Produce transcript-v1 signed request headers without a broker (the no-broker path). Supports --curl to print a ready-to-run request the adapter accepts. Tampering with the signed request causes request_binding_mismatch. → Request binding

verify

Verify a passport against a public key or a local bundle.

trustplane verify \
  --token "$TOKEN" \
  --bundle trustplane-bundle.json \
  --kid "$KEY_ID" \
  --issuer "$ISSUER" \
  --audience example-api \
  --trust-domain example.local

bundle build

Compile a local authoring config into a deterministic trustplane-bundle-v1 policy bundle skeleton. Sign reviewed outputs before production-style adapter loading. → Bundle policy & freshness

trustplane bundle build --config bundle.config.json --out trustplane.bundle.json

bundle merge-source

Non-destructively append a client public key + a route source rule to existing trust material and policy bundle (existing entries preserved; --replace-existing required for duplicates). → Trust anchors

trustplane bundle merge-source \
  --trust-material trust-material.json \
  --policy-bundle trustplane.bundle.json \
  --out-trust-material trust-material.merged.json \
  --out-policy-bundle trustplane.bundle.merged.json \
  --issuer https://issuer.acme.demo/external-jwks \
  --trust-domain acme.demo.external \
  --kid hosted-demo-client-2 \
  --public-key "$CLIENT_PUBLIC_KEY_B64URL" \
  --route-id acme.demo.orders.read \
  --subject-exact external:jwks:hosted-demo-client-2 \
  --required-key-binding software

bundle remove-source

Remove a trusted key and matching route source selector while preserving unrelated trust material and policy. Destructive removal requires --confirm-remove.

trustplane bundle remove-source \
  --trust-material trust-material.json \
  --policy-bundle trustplane.bundle.json \
  --out-trust-material trust-material.removed.json \
  --out-policy-bundle trustplane.bundle.removed.json \
  --issuer https://issuer.acme.demo/external-jwks \
  --trust-domain acme.demo.external \
  --kid hosted-demo-client-2 \
  --route-id acme.demo.orders.read \
  --subject-exact external:jwks:hosted-demo-client-2 \
  --confirm-remove \
  --revoke

bundle sign / bundle verify

Sign reviewed trust material or policy bundles, then verify the signed output before mounting. → Signed bundle lifecycle

trustplane bundle sign \
  --policy-bundle trustplane.bundle.json \
  --out trustplane.bundle.signed.json \
  --signer-issuer local://bundle-signer \
  --kid bundle-signing-key-1 \
  --private-key "$BUNDLE_SIGNING_PRIVATE_KEY_B64URL"

trustplane bundle verify \
  --policy-bundle trustplane.bundle.signed.json \
  --public-key "$BUNDLE_SIGNING_PUBLIC_KEY_B64URL"

broker issue

Ask the local broker to issue a request-bound passport + proof for a specific call. → Broker

trustplane broker issue \
  --method GET --path /orders \
  --audience acme.demo.orders --route-id acme.demo.orders.read

up

One-command local orchestrator: starts a software-signer broker (Unix socket), writes local bundle files, and starts a transcript-v1 adapter with in-memory replay + bundle policy. Demo / developer use only.

trustplane up

demo

Run the bundled end-to-end demonstration (issue + verify + protected-service example).

auth-plane

A v0.2.x command for running the auth-plane runtime locally.

enroll

Available in v0.2.1 and later. Enroll a workload key through a Control Trust Anchor enrollment policy. The CLI creates or reuses a local Ed25519 private key with restrictive permissions, obtains an enrollment challenge, submits the workload identity proof (for Kubernetes, a projected ServiceAccount OIDC token), polls with backoff, and stores the enrolled key locally along with a non-secret enrollment cache. The derived key inherits the selected existing client’s protected-resource policy.

trustplane enroll \
  --control-url "$TP_CONTROL_URL" \
  --policy "$TP_POLICY_REF" \
  --private-key-out "$TP_PRIVATE_KEY" \
  --provider oidc_jwks \
  --proof-file "$TP_PROOF_FILE" \
  --timeout=5m

Flags (v0.2.4)

Flag	Purpose
--control-url	Control base URL to enroll against.
--policy / --enrollment-policy	Opaque Enrollment Policy reference.
--provider	Enrollment provider kind (default oidc_jwks).
--private-key-file	Use an existing local private key file.
--private-key-out	Write the created private key to this path.
--replace-private-key	Allow replacing an existing private key.
--cache-file	Non-secret enrollment cache file.
--proof-file	Read the workload identity proof from a file.
--proof-stdin	Read the workload identity proof from stdin.
--kubernetes-token-file	Kubernetes token path (defaults to the projected ServiceAccount token path).
--ci-token-file	CI OIDC token file.
--ci-token-env	Environment variable holding the CI OIDC token.
--spiffe-jwt-file	SPIFFE JWT-SVID file.
--spiffe-workload-api	SPIFFE Workload API endpoint.
--aws-iid-document-file	AWS EC2 instance identity document file.
--aws-iid-signature-file	AWS EC2 instance identity signature file.
--azure-pkcs7-file	Azure PKCS7 attestation file.
--azure-compute-metadata-file	Azure compute metadata file.
--azure-imds-attested-document	Fetch the Azure IMDS attested document.
--wait-for-activation	Wait for the enrolled key to become active (default true).
--poll-interval	Polling interval while waiting for activation.
--timeout	Overall enrollment timeout.
--refresh-skew	Re-enroll this far before key expiry.
--force-reenroll	Force re-enrollment even if a cached enrollment exists.
--submit-retries	Proof-submission retries (default 2, max 5).

Exactly one of --private-key-file or --private-key-out must be set.

--wait-for-activation, --poll-interval, --refresh-skew, and --submit-retries implement bounded polling and renewal: the CLI waits for activation with a bounded poll loop and supports re-enrolling before key expiry rather than letting the derived key lapse.

Provider values

Valid --provider values: oidc_jwks (default), ci_oidc, spiffe, kubernetes_service_account_oidc, aws_ec2_iid, gcp_instance_identity, azure_instance_identity, software_manual.

The generic OIDC JWKS profile (--provider oidc_jwks, with a projected ServiceAccount token as proof) and the manual key registration path (software_manual) are supported. The other provider values (ci_oidc, spiffe, kubernetes_service_account_oidc, aws_ec2_iid, gcp_instance_identity, azure_instance_identity) are selectable but not currently supported — see Trust Anchor source availability.

Stable error strings

Enrollment errors are stable strings, for example: control_url_and_policy_required, set_exactly_one_private_key_file_or_out, invalid_enroll_timing, unsupported_enrollment_provider.

The full operator flow — Trust Anchor source registration, enrollment policy, projected-token configuration, key lifetime, and troubleshooting — is documented in OIDC JWKS enrollment runbook.

Related make targets

When building from source, the CLI commands are wrapped by convenience Makefile targets:

Target	What it runs
make build	Build trustplane, trustplane-adapter, trustplane-broker from source
make demo	trustplane demo + protected-service example
make demo-bundle	Local trust-bundle key resolution demo
make demo-adapter	Brownfield adapter (valid / 401 / 403)
make demo-provider-gateway	Broker + transcript-v1 + replay + deny reasons
make transcript-conformance	Go/JS/Python transcript-v1 conformance
make v01-acceptance	The canonical local readiness gate
make boundaries	Package import boundary checks
make docker-demo	Docker-based demo

Next steps

• Install & artifacts
• Request binding
• Quickstart