host-identity-cli 1.0.0

Command-line interface for host-identity: print a stable host UUID across platforms, clouds, and Kubernetes
Documentation

host-identity — a CLI for host-identity

Resolve a stable, collision-resistant host UUID across platforms, container runtimes, cloud providers, and Kubernetes. This crate ships the host-identity binary as a thin wrapper over the host-identity library; use the library directly if you need to embed the same logic in another program.

Install

cargo install host-identity-cli

This gives you the host-identity executable on your PATH. The binary is called host-identity to avoid colliding with coreutils hostid(1), which ships on Linux and the BSDs. The crate name (host-identity-cli) differs from the binary name (host-identity) and from the library crate name (host-identity) — cargo install host-identity has no binary and will not do what you want; always use the -cli suffix.

Default features enable both local (machine-id, DMI, container) and network (cloud metadata, Kubernetes) sources. To build a strictly local binary:

cargo install host-identity-cli --no-default-features --features container

Usage

# Print the host UUID (default chain, local sources only).
host-identity

# Same, but include cloud-metadata and Kubernetes sources.
host-identity resolve --network

# Walk every source without short-circuiting — useful for diagnostics.
host-identity audit

# List every source identifier compiled into this binary.
host-identity sources

# Build a custom chain from source identifiers.
host-identity resolve --sources env-override,machine-id,dmi

# Machine-readable output.
host-identity resolve --format json
host-identity audit --format json

Flags

Flag Values Default Notes
--format plain, summary, json plain summary prints source:uuid; plain prints only UUID.
--wrap v5, v3, passthrough v5 UUID derivation strategy. v3 matches legacy Go tooling.
--sources <ids> comma-separated source IDs (unset) Build a custom chain; see host-identity sources.
--network (flag) off Adds cloud / k8s sources (requires network feature).

Subcommands

Subcommand Purpose
resolve Resolve and print the host identity (default when omitted).
audit Walk every source in the chain and report each outcome.
sources List every source identifier compiled into this binary.

Features

Feature Default Pulls in
container yes host-identity/container
network yes ureq + every cloud feature of host-identity + host-identity/k8s

Without network, --network at runtime produces an error directing the user to rebuild with the feature.

Packaging

A man page is committed at man/host-identity.1 (plus one page per subcommand) at the workspace root. Packagers should install it to $PREFIX/share/man/man1/host-identity.1. See the top-level README.md for the full install recipe. The pages are regenerated from the clap metadata with cargo xtask.

See also

License

Dual-licensed under Apache-2.0 or MIT at your option.