BenefitsCLI docsRelease 0.4.0Get started
CLI documentation

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 --locked

The 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 release

Edit 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 --recompute

Signing 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 build

Repeat --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_TOKEN

Identity 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 json

The 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 json

Only 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,success

Exit 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.json

The 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.yaml

attest 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 json

Export 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 --help

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