bc-envelope-cli 0.33.0

Gordian Envelope Command Line Tool.
Documentation

envelope

A command line tool for manipulating the Gordian Envelope data type, written in pure Rust.

by Wolf McNally & Christopher Allen

NOTE: Preview version. Not ready for production use.

Installation

From crates.io (Recommended)

To install the latest stable version from crates.io, run:

cargo install bc-envelope-cli

To install a specific version:

cargo install bc-envelope-cli --version 0.33.0

From Source

When building from source, we strongly recommend building from a tagged release rather than the tip of the main branch, which may contain unstable code or breaking changes:

# Clone the repository
git clone https://github.com/BlockchainCommons/bc-envelope-cli-rust.git
cd bc-envelope-cli-rust

# List available tags
git tag -l

# Checkout the most recent tag
git checkout $(git describe --tags --abbrev=0)

# Install the tool
cargo install --path .

If you must build from the main branch, be aware that it may have dependency mismatches or other issues:

# Build without installing (debug build)
cargo build

# Test before installing
cargo test

# If all tests pass, you can install
cargo install --path .

Make sure your ~/.cargo/bin directory is in your PATH.

Troubleshooting Build Issues

If you encounter build problems:

  1. Try debug build first: cargo build instead of cargo build --release
  2. Check dependency versions: The main branch might require specific versions of dependencies
  3. Verify compatible Rust version: Run rustc --version to check your Rust version
  4. Build from a release tag: Tagged releases have been tested and should build properly

For serious build issues, please open an issue on the GitHub repository with details about your environment and the errors you're seeing.

Usage

envelope --help

See the docs directory for more information.

NOTE: The envelope tool does not have the same command line syntax as the Swift envelope tool.

Version History

0.33.0: February 1, 2026

  • Add envelope xid edge subcommand with add, remove, find, all, at, and count operations for verifiable claims (edges).
  • Overhaul XID documentation: split monolithic XID.md into focused sub-pages (Basics, Export, Keys, Methods, Delegates, Services, Provenance, Signing, Attachments, Edges).
  • Add comprehensive tests for XID edge functionality.
  • Add expected-text-output-rubric annotations throughout test files.
  • Update test expectations across multiple test suites.
  • Align to dependencies: bc-envelope ^0.42.0, bc-envelope-pattern ^0.13.0, bc-xid ^0.21.0, provenance-mark ^0.22.0.
  • Format.

0.32.0: January 20, 2026

  • Add xid resolution subcommand for managing dereferenceVia assertions
  • Support envelope-wrapped keys in verify command
  • Add --verify flag to read-only XID key commands
  • Add read/write password arguments to XID commands
  • Add unit subject type
  • Align to dependencies (bc-envelope-pattern, bc-xid, provenance-mark)

0.31.2: January 12, 2026

  • Update to bc-envelope 0.41.1 with fix for Envelope::unit()

0.31.1: January 12, 2026

  • Add --verify flag to read-only XID key commands (key all, key at, key count, key find inception, key find name, key find public) for signature verification
  • Support envelope-wrapped keys in verify command, allowing keys extracted from XID documents to be used directly
  • Add unit subject type to create envelopes representing deliberate emptiness
  • Fix handling of signed envelopes in XID key retrieval commands
  • Fix README

0.31.0: January 12, 2026

  • Add xid export command with controlled private key and generator handling.
  • Add --private and --generator options to all XID-modifying commands.
  • Improve documentation for XID export workflows.
  • Add comprehensive tests for export functionality.

0.30.0: December 19, 2025

  • Add full support for XID documents with attachments.
  • Add attachment commands: add, remove, count, find, all, at.
  • Add documentation for XID attachments.
  • Align to dependencies.

0.29.0: December 5, 2025

  • Align to dependencies.
  • Add rand crate for OsRng to fix SSH key encryption compatibility.
  • Update which crate to 8.0.

0.28.0: December 4, 2025

  • Align to dependencies.
  • Support abbreviated commands.
  • Add CBOR size to info command.
  • Refactor envelope parsing logic.

0.27.0: November 12, 2025

  • Add XID provenance mark support ('xid provenance get' and 'xid provenance next' commands).
  • Add XID signing and verification support (--sign and --verify options).
  • Update XID documentation.
  • Align to dependencies.

0.26.1: November 3, 2025

  • Add encryption support for provenance mark generator.
  • Change default generator option to omit.
  • Update bc-xid dependency to 0.15.1.
  • Format.

0.26.0: November 3, 2025

  • Align to dependencies.
  • Replace generate signer/verifier commands with keypairs command.
  • Add signing and encryption options to generate prvkeys.
  • Add generator options to xid new command.
  • Update documentation.

0.24.0: October 20, 2025

  • Add walk subcommand for navigating and manipulating envelope nodes.
  • Change terminology from uncompress to decompress.
  • Fix provenance-mark tag registration bug.
  • Align to dependencies.

0.23.1: September 29, 2025

  • Fixed bug where the proper tag for provenance-mark was not being registered.

0.23.0: September 26, 2025

  • Added support for ur:envelope seed format to the 'generate prvkeys --seed' command.

0.25.0: October 21, 2025

  • Add walk replace subcommand.
  • Add XID private key encryption support.
  • Align to dependencies.

0.22.0: September 16, 2025

  • Align to dependencies.
  • Fix error handling in attachment vendor command.
  • Fix error handling in SSH key generation.
  • Fix error handling in SSKR split operation.
  • Fix error handling in XID document operations.

0.21.0: July 6, 2025

  • Align to dependencies.

0.20.0: July 5, 2025

  • Align to dependencies.

0.19.0: July 3, 2025

  • Updated to latest envelope patex syntax
  • Integrated dcbor patex matching
  • Add new pattern matching tests and test utilities
  • Fix Date type references in extract command
  • Update extensive documentation

0.13.1: May 9, 2025

  • Fixed bug that would cause a crash when finding assertions that have their own assertions.

0.13.0: April 28, 2025

  • Maintenance release.

0.12.0: February 4, 2025

  • Maintenance release.

0.11.0: December 24, 2024

  • Added support for XID Document Services.
  • Endpoints in XID keys are now deprecated in favor of services.

0.10.0: December 15 2024

  • Started adding support for XID Documents.
  • Anywhere in envelope that accepts a ur:envelope can also accept any other UR types containing envelopes, including XID documents.

0.9.3: December 1, 2024

  • Aligned to dependencies.

0.9.2: October 16, 2024

  • Schnorr signatures are now BIP-340 compliant.

0.9.1: July 12, 2024

  • Fixed bug that would cause certain valid combinations of SSKR shares to be rejected.