Skip to content

cli.md

Latest commit

 

History

History
444 lines (294 loc) · 12 KB

cli.md

File metadata and controls

444 lines (294 loc) · 12 KB

tea-cli Reference

Command-line client for the Transparency Exchange API (TEA).

Synopsis

tea-cli [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS]

Description

tea-cli is a command-line interface for the Transparency Exchange API (TEA) v0.4.0. It discovers, searches, and retrieves software transparency artifacts (SBOMs, VEX, build metadata) from TEA-compliant servers.

Output is rich-formatted by default (tables, panels) for interactive use. Use --json for machine-readable JSON output suitable for piping.

tea-cli is part of the libtea Python library, maintained by sbomify.

Installation

pip install libtea[cli]

Global Options

Option Description
--json Output raw JSON instead of rich-formatted tables
--verbose, -v Show verbose output (libtea debug logs on stderr, suppresses urllib3/requests noise)
--debug, -d Show full debug output (all HTTP requests, urllib3, timing) on stderr
--allow-private-ips Allow artifact downloads from private/internal IPs (relaxes SSRF checks for downloads only). Scheme validation and cloud metadata endpoint blocking are always enforced.
--version Show version and exit
--help Show help message and exit

-v and -d can be combined: -v -d is equivalent to -d alone (full firehose).

Connection Options

Every command accepts the following options for server selection and authentication.

Option Description
--base-url URL TEA server base URL (e.g. https://trust.sbomify.com/tea/v0.4.0). Can also be set via the TEA_BASE_URL environment variable. Mutually exclusive with --domain.
--domain DOMAIN Discover server from the domain's .well-known/tea endpoint. The domain can also be auto-extracted from a TEI URN argument.
--token TOKEN Bearer token for authentication. Prefer the TEA_TOKEN environment variable to avoid exposing the token in shell history.
--auth USER:PASSWORD HTTP basic authentication credentials. Prefer the TEA_AUTH environment variable to avoid exposing credentials in shell history. Mutually exclusive with --token.
--timeout SECONDS Request timeout in seconds (default: 30).
--use-http Use HTTP instead of HTTPS for .well-known/tea discovery. Intended for local development only.
--port PORT Port for well-known resolution (overrides the default for the scheme).
--allow-private-ips Allow artifact downloads from private/internal IPs. Useful when the TEA server or its artifacts are hosted on a local network.

Commands

discover

Resolve a TEI URN to product release UUID(s).

tea-cli discover [--quiet | -q] TEI

Arguments:

Argument Description
TEI A TEI URN (e.g. urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify). The domain is auto-extracted for server discovery when --base-url and --domain are omitted.

Options:

Option Description
--quiet, -q Output only UUIDs, one per line. Useful for scripting.

inspect

Full flow: TEI -> discovery -> product releases -> components -> artifacts. Resolves a TEI and fetches the full object graph in one shot.

tea-cli inspect [--max-components N] TEI

Options:

Option Description
--max-components N Maximum number of components to fetch per release (default: 50).

search-products

Search for products by identifier.

tea-cli search-products --id-type TYPE --id-value VALUE [--page-offset N] [--page-size N]

Options:

Option Description
--id-type TYPE Identifier type: CPE, TEI, or PURL.
--id-value VALUE Identifier value to search for.
--page-offset N Page offset for pagination (default: 0).
--page-size N Page size for pagination (default: 100).

search-releases

Search for product releases by identifier.

tea-cli search-releases --id-type TYPE --id-value VALUE [--page-offset N] [--page-size N]

Options are the same as search-products.

get-product

Get a product by UUID.

tea-cli get-product UUID

get-product-releases

List releases for a product UUID.

tea-cli get-product-releases UUID [--page-offset N] [--page-size N]

Options:

Option Description
--page-offset N Page offset for pagination (default: 0).
--page-size N Page size for pagination (default: 100).

get-release

Get a product or component release by UUID.

tea-cli get-release [--component] UUID

Options:

Option Description
--component Get a component release instead of a product release.

get-component

Get a component by UUID.

tea-cli get-component UUID

get-component-releases

List releases for a component UUID.

tea-cli get-component-releases UUID

get-collection

Get a collection (latest or by version).

tea-cli get-collection [--version N] [--component] UUID

Options:

Option Description
--version N Collection version number. If omitted, returns the latest collection.
--component Get from component release instead of product release.

list-collections

List all collection versions for a release UUID.

tea-cli list-collections [--component] UUID

Options:

Option Description
--component List collections for a component release instead of a product release.

search-components

Search for components by identifier.

tea-cli search-components --id-type TYPE --id-value VALUE [--page-offset N] [--page-size N]

Options are the same as search-products.

search-component-releases

Search for component releases by identifier.

tea-cli search-component-releases --id-type TYPE --id-value VALUE [--page-offset N] [--page-size N]

Options are the same as search-products.

get-artifact

Get the latest revision of artifact metadata by UUID.

tea-cli get-artifact UUID

get-artifact-version

Get a specific version of artifact metadata by UUID.

tea-cli get-artifact-version UUID VERSION

Arguments:

Argument Description
UUID Artifact UUID.
VERSION Artifact version number (starts at 1).

download

Download an artifact file with optional checksum verification.

tea-cli download URL DEST [--checksum ALG:VALUE]... [--max-download-bytes N]

Arguments:

Argument Description
URL Artifact download URL.
DEST Local file path to save the downloaded artifact.

Options:

Option Description
--checksum ALG:VALUE Checksum to verify, as ALGORITHM:HEX_VALUE. Can be specified multiple times. Supported algorithms: MD5, SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2b-256, BLAKE2b-384, BLAKE2b-512.
--max-download-bytes N Maximum download size in bytes. The download is aborted if the response exceeds this limit.

get-cle

Get Common Lifecycle Enumeration (CLE) events for an entity.

tea-cli get-cle [--entity TYPE] UUID

Options:

Option Description
--entity TYPE Entity type: product, product-release (default), component, or component-release.

conformance

Run conformance checks against a TEA server. Validates that the server correctly implements the TEA specification by running 27 checks covering discovery, products, releases, components, artifacts, CLE, and cross-cutting concerns.

tea-cli conformance --base-url URL [OPTIONS]

Options:

Option Description
--base-url URL TEA server base URL (required). Can also be set via TEA_BASE_URL.
--tei TEI TEI URN for discovery-driven testing. Seeds the check context with a product release UUID discovered from the TEI.
--product-uuid UUID Explicit product UUID for direct testing.
--release-uuid UUID Explicit product release UUID.
--component-uuid UUID Explicit component UUID.
--component-release-uuid UUID Explicit component release UUID.
--artifact-uuid UUID Explicit artifact UUID.
--token TOKEN Bearer token. Can also be set via TEA_TOKEN.
--auth USER:PASSWORD Basic auth credentials. Can also be set via TEA_AUTH.
--timeout SECONDS Request timeout in seconds (default: 30).
--allow-private-ips Allow private IPs in downloads.
--json Output results as JSON.
-v, --verbose Show failure details and increase logging verbosity.
-d, --debug Show debug output.

The command exits with code 0 if all checks pass, and code 1 if any check fails.

See the conformance docs for the full check reference and pytest plugin usage.

Environment Variables

Variable Description
TEA_BASE_URL TEA server base URL. Equivalent to --base-url.
TEA_TOKEN Bearer token. Equivalent to --token. Preferred over the command-line flag to avoid exposing the token in shell history.
TEA_AUTH Basic auth credentials as USER:PASSWORD. Equivalent to --auth.

Authentication

tea-cli supports three authentication methods, all mutually exclusive:

Bearer token (most common): Pass via --token or TEA_TOKEN. Requires HTTPS. The token is never sent to artifact download URLs (CDNs) — only to the TEA API server.

HTTP basic auth: Pass via --auth USER:PASSWORD or TEA_AUTH. Requires HTTPS.

Using credentials over plaintext HTTP raises an error. Use --use-http only for unauthenticated local development.

Examples

Discover sbomify product releases:

tea-cli discover "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"

Full inspection with JSON output:

tea-cli --json inspect "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"

Search for a product by PURL:

tea-cli search-products \
    --id-type PURL \
    --id-value "pkg:github/sbomify/sbomify" \
    --domain trust.sbomify.com

Get lifecycle events for a product release:

tea-cli get-cle --entity product-release <uuid> \
    --domain trust.sbomify.com

Download an artifact with checksum verification:

tea-cli download "https://cdn.example.com/sbom.json" ./sbom.json \
    --checksum "SHA-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
    --domain trust.sbomify.com

Pipe UUIDs to another tool:

tea-cli discover -q "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify" | \
    xargs -I {} tea-cli --json get-release {} --domain trust.sbomify.com

Verbose logging to diagnose issues:

# libtea debug logs only (no urllib3 noise)
tea-cli -v discover "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"

# Full HTTP firehose
tea-cli -d discover "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"

Local development with private IPs:

# Allow downloads from a local TEA server
tea-cli download "http://192.168.1.100:8080/sbom.json" ./sbom.json \
    --allow-private-ips --base-url "http://192.168.1.100:8080/tea/v0.4.0"

Using environment variables to avoid repeating credentials:

export TEA_TOKEN="your-bearer-token"
export TEA_BASE_URL="https://trust.sbomify.com/tea/v0.4.0"
tea-cli discover "urn:tei:purl:trust.sbomify.com:pkg:github/sbomify/sbomify"
tea-cli get-product <product-uuid>

Exit Status

Code Meaning
0 Success
1 Error (network failure, authentication error, not found, invalid input, etc.). The error message is printed to stderr.

See Also