CLI reference
This reference follows continuum-attest/src/main.rs at version 0.4.0.
Use attest --help and attest <command> --help for the exact options of the
binary installed on your machine. Global options are --verbose and --quiet.
Installation
Continuum Attest 0.4.0 supports Linux and macOS, on x86-64 and arm64, under Apache-2.0. See the release files for binaries and verification material. Windows is not supported in this release.
Install with Cargo
The package is continuum-attest on
crates.io. Install it with Rust 1.89 or later:
cargo install continuum-attest --version 0.4.0 --lockedThe installed command is attest. The crate named attest belongs to another
project.
First signed receipt
From your project's directory, initialize Continuum Attest and create a signing key:
attest init
attest keys generate --name releaseEdit the generated attest.yaml to declare your build command, input files and
outputs. Then execute it and verify the receipt against your workspace:
attest run --sign
attest verify .attest/receipts/*.yaml --recomputeSigning is explicit. Keep private keys private; a recipient needs the receipt and independently approved public keys to check its signature. Recomputing file hashes also requires the corresponding workspace files.
The public Receipt format specifies the evidence and signing rules. The Plugin protocol is a draft; version 0.4.0 does not execute plugins.
Commands
| Command | Purpose |
|---|---|
attest init |
Create the local workspace and a starter pipeline |
attest run |
Execute a pipeline or wrap one command |
attest sign |
Sign a receipt in a process that ran no project command |
attest timestamp |
Timestamp an existing receipt signature without a private key |
attest identity sign |
Bind the exact receipt bytes to a CI workflow using Cosign 3 |
attest evidence |
Package artifacts and proofs, or verify them offline |
attest trust |
Create, inspect, import or refresh signed trust bundles |
attest keys |
Generate, list, export, import or revoke keys; pin a timestamp authority |
attest hash |
Compute canonical hashes of declared paths |
attest capsule |
Initialize, run or hash an execution capsule |
attest verify |
Check receipts or an offline archive |
attest export |
Export a receipt as an in-toto DSSE envelope |
attest import |
Verify an imported in-toto DSSE envelope |
attest image |
Image signing and verification operations |
attest causal |
Inspect causal history, publish a commitment or fetch a log comparison proof |
Run a pipeline
attest run --pipeline attest.yaml --sign
attest run --sign --key <key-id>
attest run --check-reproducibility
attest run --sign --timestamp--verify selects process isolation: resource limits, without network or
filesystem control. The receipt’s isolation block reports controls as
enforced, not enforced or unavailable. It does not replace attest verify
on the resulting receipt. --check-reproducibility runs the
pipeline twice in fresh workspaces and compares output hashes. Use
the configuration reference for step fields.
Wrap one command
attest run --wrap --name build --input src/ --output dist/ --report build-report.json -- npm run buildRepeat --input and --output for multiple paths. --workspace DIR chooses
the root. Wrap mode runs without a pipeline file or sandbox; signing can be
added with --sign and a provisioned key. The JSON report names the exact receipt
and preserves the build exit code separately from evidence production.
New wrapped receipts record the canonical command argument vector. A recipient
can recompute the declared input and output hashes without attest.yaml, by
transferring the declared files and using attest verify --recompute. No command
is executed during verification. Input permission guards and post-build hash
checks detect persistent input changes; they do not provide a sandbox.
The public CI adoption guide
contains pinned GitHub action and GitLab component examples. Both distinguish
build, receipt, signing, timestamp, verification and publication outcomes, with
an explicit evidence-policy: required or optional. A build failure retains
its exit code; required evidence failure after a successful build fails CI.
Real GitHub Actions and self-managed GitLab jobs have passed the offline
acceptance and refusal scenarios recorded in
#25.
Self-managed GitLab identity signing needs services that recognize its issuer
and independently configured recipient trust. Qualification used temporary
test infrastructure; it does not provide a production signing service.
Workflow identity
attest identity sign receipt.yaml --bundle identity.sigstore.json
attest identity sign receipt.yaml --bundle identity.sigstore.json \
--identity-token-env ATTEST_CI_ID_TOKENIdentity signing requires network access, a pinned Cosign 3 binary and the CI provider's OIDC permission or token. The recipient supplies a policy pinning the issuer, repository, complete workflow identity and expected source revision, plus an independently trusted Sigstore root. Environment variables alone do not establish workflow identity. The local Ed25519 receipt signature remains required. Identity proves origin and authorization, not runner integrity.
Offline release evidence
attest evidence pack receipt.yaml --output release.attest.tar.zst \
--identity-bundle identity.sigstore.json
attest evidence verify release.attest.tar.zst --trust-store /trusted/keys \
--identity-policy /trusted/workflow-policy.json --format json
attest evidence verify release.attest.tar.zst --trust-store /trusted/keys \
--artifact-root /delivery/artifacts --format jsonThe recipient provisions trust independently of the archive. Verification always
requires a trusted signature, successful execution and matching artifact bytes.
The default policy also requires complete referenced capsule and causal proofs;
--identity-policy adds the required workflow identity. --artifact-root checks
separately delivered files, preserving their declared relative paths.
Packing includes available referenced causal events. Add repeatable
--capsule-manifest FILE options for referenced capsules. Missing required
proofs or altered proofs prevent acceptance. An explicit
--require signature,success,artifacts can permit incomplete optional proofs;
their skipped results remain visible. JSON includes policy.required,
policy.unmet, identity requirements, verified claims and separate principals.
No trust material or missing proof is fetched during verification.
Compatibility: 0.4 writes attest-evidence/v3 when a publication record is
included, and v2 otherwise. Upgrade recipients to 0.4 before sending log proofs;
older verifiers refuse v3. Existing v1 and v2 packages remain readable. See the
evidence format.
These packages are distinct from the causal archives accepted by attest verify --archive.
Publish a commitment and deliver its proof
Glass Ocean adds explicit publication to a compatible external log. Choose the operator and provision its key independently for recipients. Attest does not select or operate a public log. Running a build alone never publishes an entry.
attest causal publish --receipt receipt.yaml --log-config producer-log.json \
--output publication.json --publication-policy required --format json
attest evidence pack receipt.yaml --workspace . --publication publication.json \
--output release.attest.tar.zst
attest evidence verify release.attest.tar.zst --trust-store /trusted/keys \
--log-trust recipient-log.json --require signature,success,artifacts,log-inclusion --format jsonOnly verified inclusion under a trusted signed checkpoint confirms publication.
required exits 3 if confirmation is unavailable; optional retains an
unconfirmed record and its reason with exit 0. Local errors exit 2. Keep
publication.json to resume the same submission safely. The recipient can
require log-inclusion regardless of the producer's policy.
Publication is irreversible. Read Publish and verify log evidence for disclosure, configuration, CI adoption and comparison of independently obtained checkpoints. Log inclusion and consistency belong to evidence verification, not the ordinary receipt verification contract below.
Verify receipts
attest verify .attest/receipts/<receipt>.yaml
attest verify --recompute .attest/receipts/<receipt>.yaml
attest verify --trust-store /path/to/trust --format json receipt.yaml
attest verify --archive bundle.attest.tar.zst --offline
attest verify receipt.yaml --recompute --require signature,timestamp,recompute
attest verify --archive bundle.attest.tar.zst --offline --require signature,linkage,trust,successExit codes are 0 for success, 1 for a failed verification and 2 for an operational
error. JSON output is NDJSON. Signature checking defaults to true;
--check-signatures false explicitly allows checks of an unsigned receipt and
does not establish signer trust. See Receipts and trust.
A check that did not run is skipped and never satisfies a --require
requirement. This option requires a result; it does not enable a check:
add --recompute to perform recomputation. Supported properties are signature, timestamp, recompute,
linkage (archives), trust (a current bundle) and success (every step exited
0). The result distinguishes valid evidence from a successful build. Receipt
JSON adds policy, execution and trust_material; its contract is published
in the verification result v1 schema.
Archives default to limits of 64 MiB on disk, 512 MiB unpacked, 10 000 entries
and 64 MiB per entry. Receipts and DSSE envelopes are limited to 16 MiB before
parsing. Exceeding a limit produces exit code 2 and JSON error kind
resource-limit.
Share trust
attest trust bundle --output trust.json --key <issuer-key-id>
attest trust show trust.json
attest trust import trust.json --issuer <issuer-key-id>
attest trust refresh trust-2.jsonThe producer signs trusted keys and dated revocations into a bundle with a validity window and sequence number. The recipient obtains the issuer’s key id through a separate trusted channel before the first import. Updates older than the accepted sequence, tampered bundles and revoked issuers are refused. Authority rotation uses a successor named in the signed bundle. Import and refresh remain explicit and offline. The verdict reports bundle freshness against the local clock; it cannot know about revocations published after the last update.
Sign after the build
attest sign receipt.yaml --key <key-id> --timestamp --output signed-receipt.yaml
attest timestamp signed-receipt.yaml --output timestamped-receipt.yamlattest sign signs in a process that ran no project command. ATTEST_KEYS_DIR
keeps private keys outside the workspace. With attest run --sign, the key is
loaded only after the last step exits. --timestamp and --key without
--sign are refused on attest run.
Timestamp requests require HTTPS, including custom --tsa URLs and redirects.
The default is https://timestamp.sectigo.com/rfc3161. Provision the authority's
issuing CA through an independent trusted channel before verification.
attest timestamp does not re-sign the receipt or load a private key.
Keys and hashes
attest keys generate --name ci
attest keys list
attest keys export <key-id> --output ci.pub
attest keys import ci.pub --name team-ci
attest keys revoke <key-id>
attest keys trust-tsa sectigo-ca.crt --name sectigo
attest hash --input src/ --run 'npm run build'
attest hash --output dist/Key export contains public material only. See key management for CI provisioning and rotation.
Standard-format exchange
attest export --receipt receipt.yaml --format in-toto --output statement.json
attest import statement.json --format in-toto --report jsonExport signs the envelope using an available key; --key selects it.
--allow-unsigned explicitly permits unsigned export. Import verifies an
envelope against the trust store; it is not an upload to the SaaS.
New SLSA projections carry the original signed receipt, signer, timestamp and
public trust context. The importer checks the DSSE signer and original receipt
authority separately; re-signing cannot authorize an unknown or revoked original
signer. Subjects contain digests of actual artifact files, so export needs those
files in the workspace. Workflow builder identity is verified with both
--identity-bundle and --identity-policy, or is explicitly unverified.
Import accepts --identity-policy and --artifact-root for recipient checks.
Multiple envelope signatures are explicitly refused. Legacy imports report
narrower guarantees. The versioned
build-type specification
defines this projection; it does not claim a SLSA build level.
Additional command groups
attest capsule --help
attest image --help
attest causal --helpCapsule initialization requires a digest-pinned OCI reference rather than a tag and capsule execution needs a container runtime. Review these paths in your environment before adopting them. The developer guide identifies their source and tests.
Commands such as attest login, attest publish, attest deploy, attest status
and attest cache are not exposed by the current binary.