This package defines an OmniBOR Command Line Interface, intended to enable easier generation and handling of OmniBOR identifiers and manifests.

[!NOTE] This is currently a work-in-progress. Today, the omnibor CLI only supports working with identifiers, not manifests.

This command is intended to enable integration with shell scripts and other programs where the overhead of integrating directly with the omnibor crate through the C-language Foreign Function Interface (FFI) may not be worthwhile, and where the cost of running a shell to execute this CLI isn't problematic.

Installation

Install from Release (recommended)

The OmniBOR CLI provides pre-built binaries for the following platforms:

• Apple Silicon macOS
• Intel macOS
• x64 Windows
• x64 Linux
• x64 MUSL Linux

For shell (Linux and macOS; requires tar, unzip, and either curl or wget):

$ curl --proto '=https' --tlsv1.2 -LsSf "https://github.com/omnibor/omnibor-rs/releases/download/omnibor-cli-v0.6.0/omnibor-cli-installer.sh" | sh

For Powershell (Windows; requires tar, Expand-Archive, and Net.Webclient):

> powershell -c "irm https://github.com/omnibor/omnibor-rs/releases/download/omnibor-cli-v0.6.0/omnibor-cli-installer.ps1 | iex"

[!NOTE] Huge shoutout to the folks at Axo for making cargo-dist, which makes producing these binaries extremely easy.

Install with cargo-binstall

You can also use cargo-binstall to install the OmniBOR CLI. This requires both cargo and cargo-binstall to be installed.

$ cargo binstall omnibor-cli

Build from source (stable)

You can build from source using Cargo, which requires a recent-enough Rust toolchain. We do not commit to a Minimum Supported Rust Version, and generally track stable currently.

$ cargo install omnibor-cli

Build from source (unstable)

Finally, you can build from the latest source in the repository itself. While we run continuous integration testing and try not to break the build in the repository, this runs a higher risk of brokenness or incompleteness of features relative to versions published to [Crates.io].

This requires git to check out the repository, plus a recent-enough version of Rust. We do not commit to a Minimum Support Rust Version, and generally track stable currently.

# Run the following from the root of the repository after checking
# the repository out with `git clone`.
$ cargo install --path omnibor-cli

Examples

$ omnibor id Cargo.toml
# Cargo.toml => gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f

$ omnibor id Cargo.toml -f json
# {"id":"gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f","path":"Cargo.toml"}

$ omnibor id Cargo.toml -f short
# gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f

$ omnibor find gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f .
# gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f => ./Cargo.toml

$ omnibor find gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f . -f json
# {"id":"gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f","path":"./Cargo.toml"}

$ omnibor find gitoid:blob:sha256:c54d66281dea2bf213083f9bd3345d89dc6657fa554b1c9ef14cfe4bab14893f . -f short
# ./Cargo.toml

Usage

Usage: omnibor [OPTIONS] <COMMAND>

Commands:
  id    For files, prints their Artifact ID. For directories, recursively prints IDs for all files under it
  find  Find file matching an Artifact ID
  help  Print this message or the help of the given subcommand(s)

Options:
  -b, --buffer <BUFFER>  How many print messages to buffer at one time, tunes printing perf
  -h, --help             Print help
  -V, --version          Print version

For files, prints their Artifact ID. For directories, recursively prints IDs for all files under it

Usage: omnibor id [OPTIONS] <PATH>

Arguments:
  <PATH>  Path to identify

Options:
  -f, --format <FORMAT>  Output format (can be "plain", "short", or "json") [default: plain]
  -H, --hash <HASH>      Hash algorithm (can be "sha256") [default: sha256]
  -h, --help             Print help

Find file matching an Artifact ID

Usage: omnibor find [OPTIONS] <URL> <PATH>

Arguments:
  <URL>   `gitoid` URL to match
  <PATH>  The root path to search under

Options:
  -f, --format <FORMAT>  Output format (can be "plain", "short", or "json") [default: plain]
  -h, --help             Print help

Output Formats

Both the id and find subcommand support a -f/--format flag which can be any of the following:

• plain (default): A simple human-readable format which maps between paths and identifiers, separated by a fat arrow (=>).
• short: Just prints the thing being searched for (for the id command, an Artifact Identifier, for the find command, a filesystem path).
• json: Prints a JSON object with path and id string-type fields.

The short format is recommended for piping or redirecting into other commands.

The json format is recommended for more structured contexts, and can be passed to jq to manipulate.

License

The OmniBOR CLI source code is licensed under the Apache-2.0 license.