### Install Host Identity to Standard Unix Locations

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Manually install the host-identity binary and man pages to standard system directories using the install command.

```bash
install -Dm755 host-identity          /usr/local/bin/host-identity
```

```bash
install -Dm644 man/host-identity.1    /usr/local/share/man/man1/host-identity.1
```

--------------------------------

### Install host-identity CLI from source (no default features)

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Install the host-identity CLI from source without default features, enabling specific features like 'container'. This is useful for building a customized local installation.

```bash
cargo install --locked host-identity-cli \
    --no-default-features --features container
```

--------------------------------

### Install and Run host-identity CLI

Source: https://github.com/dekobon/host-identity/blob/main/README.md

Install the `host-identity-cli` binary to use command-line tools for printing the resolved UUID or auditing identity sources.

```bash
cargo install host-identity-cli
host-identity                       # print the resolved UUID
host-identity audit                 # show what every identity source produced
```

--------------------------------

### Install host-identity CLI

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Install the host-identity CLI using cargo. Ensure you use the '-cli' suffix to get the executable.

```bash
cargo install host-identity-cli
```

--------------------------------

### Install host-identity on Windows using Scoop

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Install host-identity on Windows using Scoop. This involves adding the dekobon scoop bucket and then installing the host-identity package.

```bash
scoop bucket add dekobon https://github.com/dekobon/scoop-bucket && scoop install host-identity
```

--------------------------------

### Install Host Identity on FreeBSD

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Use pkg to install the prebuilt amd64 package on FreeBSD. For aarch64, use cargo install or the ports tree.

```bash
sudo pkg install ./host-identity-<ver>.pkg
```

--------------------------------

### Install host-identity binaries and man pages

Source: https://github.com/dekobon/host-identity/blob/main/docs/packaging.md

Use these commands to install the host-identity binary and its man pages to the specified prefix. Ensure the target directory structure is correctly set up.

```bash
install -Dm755 target/release/host-identity "$PREFIX/bin/host-identity"
install -Dm644 man/host-identity.1          "$PREFIX/share/man/man1/host-identity.1"
install -Dm644 man/host-identity-resolve.1  "$PREFIX/share/man/man1/host-identity-resolve.1"
install -Dm644 man/host-identity-audit.1    "$PREFIX/share/man/man1/host-identity-audit.1"
install -Dm644 man/host-identity-sources.1  "$PREFIX/share/man/man1/host-identity-sources.1"
install -Dm644 LICENSE-APACHE        "$PREFIX/share/doc/host-identity/LICENSE-APACHE"
install -Dm644 LICENSE-MIT           "$PREFIX/share/doc/host-identity/LICENSE-MIT"
install -Dm644 THIRD-PARTY-LICENSES.md "$PREFIX/share/doc/host-identity/THIRD-PARTY-LICENSES.md"
```

--------------------------------

### Install host-identity CLI with specific features

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Install the host-identity CLI without default features and enable only the 'container' feature for a strictly local binary.

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

--------------------------------

### Changelog Entry Example

Source: https://github.com/dekobon/host-identity/blob/main/docs/developer-guide.md

Example of how to format entries in the CHANGELOG.md file, following the Keep a Changelog format.

```markdown
### Added

- `Resolver::with_wrap` lets callers choose a UUID wrap strategy.
- `FnSource` wraps a user closure as a `Source`.

### Fixed

- `MachineIdFile` now rejects the `uninitialized` sentinel before
  wrapping.
```

--------------------------------

### Install host-identity-cli with Cargo

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Install the host-identity-cli using Cargo. Ensure you use the `--locked` flag for reproducible builds.

```bash
cargo install --locked host-identity-cli --force
```

--------------------------------

### Install host-identity on RHEL/Rocky/Fedora/Amazon Linux

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Install the host-identity package on RHEL, Rocky Linux, Fedora, or Amazon Linux using dnf. Substitute 'yum install' if your system uses yum. This command installs the RPM package.

```bash
sudo dnf install ./host-identity-<ver>-1.x86_64.rpm   # or .aarch64.rpm
```

--------------------------------

### Install Host Identity on Windows using Scoop

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Add the Scoop bucket and then install host-identity. This method supports both x86_64 and aarch64 on Windows.

```powershell
scoop bucket add dekobon https://github.com/dekobon/scoop-bucket
```

```powershell
scoop install host-identity
```

--------------------------------

### Install and Use host-identity-cli

Source: https://context7.com/dekobon/host-identity/llms.txt

Commands for installing the `host-identity-cli` and performing various host identity resolution tasks, including basic resolution, including cloud sources, auditing, listing sources, custom chains, output formats, wrap strategies, and app-specific derivation.

```bash
# Install the CLI
cargo install host-identity-cli
```

```bash
# Basic resolution (default local-only chain)
host-identity
```

```bash
# Include cloud/k8s sources
host-identity resolve --network
```

```bash
# Audit all sources (no short-circuit)
host-identity audit
```

```bash
# List available source identifiers
host-identity sources
```

```bash
# Custom chain from identifiers
host-identity resolve --sources env-override,machine-id,dmi
```

```bash
# Output formats
host-identity resolve --format plain     # UUID only (default)
host-identity resolve --format summary   # source:uuid
host-identity resolve --format json      # Full JSON envelope
```

```bash
# Wrap strategies
host-identity resolve --wrap v5          # UUID v5 (default)
host-identity resolve --wrap v3          # UUID v3 (Go compat)
host-identity resolve --wrap passthrough # No hashing
```

```bash
# App-specific derivation
host-identity resolve --app-id com.example.telemetry
host-identity resolve --app-id com.example.telemetry --format json
```

--------------------------------

### Clone and Build host-identity Project

Source: https://github.com/dekobon/host-identity/blob/main/docs/developer-guide.md

Clone the repository, navigate to the project directory, and build the project. Ensure you have Rust installed.

```bash
git clone https://github.com/dekobon/host-identity
cd host-identity
cargo build
```

--------------------------------

### Install host-identity on Debian/Ubuntu

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Install the host-identity package on Debian or Ubuntu systems by downloading the appropriate .deb file from the release page and using apt. This method handles dependency resolution.

```bash
sudo apt install ./host-identity_<ver>_amd64.deb      # or _arm64.deb
```

--------------------------------

### Install host-identity on macOS using Homebrew

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Install host-identity on macOS using Homebrew. This command adds the dekobon repository and installs the host-identity package, suitable for Apple Silicon Macs.

```bash
brew install dekobon/host-identity/host-identity
```

--------------------------------

### Tap and Install Host Identity on macOS using Homebrew

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Explicitly tap the Homebrew repository and then install host-identity. This method allows pinning the repository URL.

```bash
brew tap dekobon/host-identity https://github.com/dekobon/homebrew-host-identity
```

```bash
brew install host-identity
```

--------------------------------

### Install host-identity on Alpine Linux

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Install the host-identity package on Alpine Linux using apk. Since the apk is unsigned, use the `--allow-untrusted` flag. It is recommended to verify the integrity using the detached minisign signature.

```bash
sudo apk add --allow-untrusted ./host-identity-<ver>-r0.apk
```

--------------------------------

### macOS Feature Gating Example

Source: https://github.com/dekobon/host-identity/blob/main/docs/algorithm.md

Shows the identity chain on macOS with the same feature set as the Linux example. Platform-specific sources like IoPlatformUuid replace Linux-specific ones.

```text
EnvOverride → KubernetesPodUid → AwsImds<T> → IoPlatformUuid → KubernetesServiceAccount
```

--------------------------------

### Generate third-party licenses

Source: https://github.com/dekobon/host-identity/blob/main/docs/packaging.md

Install cargo-about and then use it to generate the THIRD-PARTY-LICENSES.md file. This command requires the manifest path and a Handlebars template.

```bash
cargo install cargo-about
cargo about generate --locked \
    --manifest-path crates/host-identity-cli/Cargo.toml \
    about.hbs > THIRD-PARTY-LICENSES.md
```

--------------------------------

### Conventional Commit Example

Source: https://github.com/dekobon/host-identity/blob/main/docs/developer-guide.md

An example of a conventional commit message. It includes a type, scope, subject, and a body explaining the change and referencing a GitHub issue.

```text
fix(sources): reject uninitialized sentinel on all machine-id sources

The DBus fallback was hashing the systemd sentinel instead of
rejecting it, producing colliding IDs on hosts caught in early boot.

Fixes #42
```

--------------------------------

### Upgrade and Uninstall Host Identity with Homebrew

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Commands to upgrade an existing host-identity installation, uninstall it, and optionally untap the repository.

```bash
brew upgrade host-identity
```

```bash
brew uninstall host-identity
```

```bash
brew untap dekobon/host-identity
```

--------------------------------

### Install host-identity-cli using Cargo

Source: https://github.com/dekobon/host-identity/blob/main/README.md

Installs the 'host-identity-cli' tool using Cargo, the Rust package manager. The '--locked' flag ensures that the exact versions specified in the lock file are used for reproducible builds.

```bash
cargo install --locked host-identity-cli
```

--------------------------------

### JSON output for host-identity resolve

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Example of the JSON output when using 'host-identity resolve --format json'. It includes the wrap strategy, host ID, source, and container status.

```json
{
  "wrap": "v5",
  "host_id": { "uuid": "…", "source": "machine-id", "in_container": false }
}
```

--------------------------------

### Linux Feature Gating Example

Source: https://github.com/dekobon/host-identity/blob/main/docs/algorithm.md

Illustrates the identity chain on Linux when specific features are enabled. Note that 'container' is disabled, and only 'aws' and 'k8s' features are active.

```text
EnvOverride → KubernetesPodUid → AwsImds<T> → MachineIdFile → DbusMachineIdFile → DmiProductUuid → KubernetesServiceAccount
```

--------------------------------

### Upgrade host-identity (Portable)

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Upgrade a portable installation of host-identity by replacing the extracted binary.

```bash
Replace the extracted binary
```

--------------------------------

### Get host UUID (including network sources)

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Print the host UUID, including cloud metadata and Kubernetes sources, by using the --network flag.

```bash
host-identity resolve --network
```

--------------------------------

### Implement Custom Cloud Provider

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity/README.md

Provides an example of adding a new cloud provider by implementing the `CloudEndpoint` trait. This is suitable for providers following the one-GET plaintext-response pattern.

```rust
use host_identity::{SourceKind, sources::{CloudEndpoint, CloudMetadata}};

pub type VultrMetadata<T> = CloudMetadata<VultrEndpoint, T>;

pub struct VultrEndpoint;

impl CloudEndpoint for VultrEndpoint {
    const DEBUG_NAME: &'static str = "VultrMetadata";
    const DEFAULT_BASE_URL: &'static str = "http://169.254.169.254";
    const PATH: &'static str = "/v1/instance-id";
    const KIND: SourceKind = SourceKind::custom("vultr-metadata");

    fn headers() -> &'static [(&'static str, &'static str)] { &[] }
}
```

--------------------------------

### Verify SHA256SUMS with minisign

Source: https://github.com/dekobon/host-identity/blob/main/SECURITY.md

Verify the integrity of release artifacts using minisign and SHA256SUMS. Ensure you have the minisign tool installed and the correct public key.

```bash
minisign -Vm SHA256SUMS -p minisign.pub
```

```bash
grep <artefact> SHA256SUMS | sha256sum -c
```

--------------------------------

### Build and Test Project

Source: https://github.com/dekobon/host-identity/blob/main/CONTRIBUTING.md

Clone the repository, build the project, and run all tests with all features enabled.

```bash
git clone https://github.com/dekobon/host-identity
cd host-identity
cargo build
cargo test --all-features --workspace
```

--------------------------------

### Rehearsing a Release with a Placeholder Tag

Source: https://github.com/dekobon/host-identity/blob/main/docs/cutting-a-release.md

Use a throwaway pre-release tag to rehearse the release pipeline. This requires a matching changelog entry and should be reverted after the rehearsal.

```bash
# 1. On main, append `## [0.0.0-test1]` with a one-line body to
#    crates/host-identity/CHANGELOG.md and commit.
# 2. Tag and push:
git tag -a v0.0.0-test1 -m "pipeline rehearsal"
git push origin v0.0.0-test1
# 3. After the rehearsal, revert the placeholder commit on main.
```

--------------------------------

### List available sources

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

List all source identifiers compiled into the binary. Use --json for machine-readable output.

```bash
host-identity sources
```

--------------------------------

### Configure Kubernetes Metadata Sources

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity/README.md

Demonstrates how to configure and use Kubernetes-specific metadata sources, including Pod UID, Downward API, and Service Account, for retrieving identity information within a Kubernetes cluster.

```rust
use host_identity::Resolver;
use host_identity::sources::{
    KubernetesPodUid,
    KubernetesServiceAccount,
    KubernetesDownwardApi,
};

let id = Resolver::new()
    .push(KubernetesPodUid::default())              // /proc/self/mountinfo
    .push(KubernetesDownwardApi::with_label(
        "/etc/podinfo/uid",
        "pod-uid",                                  // custom log label
    ))
    .push(KubernetesServiceAccount::default())      // namespace (fallback)
    .resolve()?;
```

--------------------------------

### Running ShellSpec Tests

Source: https://github.com/dekobon/host-identity/blob/main/docs/developer-guide.md

Build the host-identity-cli crate and then execute the ShellSpec tests using the provided command. This wraps ShellSpec and sets the necessary `HOST_IDENTITY_BIN` environment variable.

```bash
cargo build -p host-identity-cli
```

```bash
cargo xtask shellspec
```

--------------------------------

### Upgrade host-identity with Homebrew

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Upgrade the host-identity formula using Homebrew.

```bash
brew upgrade host-identity
```

--------------------------------

### Uninstall host-identity-cli with Cargo

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Uninstall the host-identity-cli when installed via Cargo.

```bash
cargo uninstall host-identity-cli
```

--------------------------------

### Uninstall host-identity (Portable)

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Uninstall a portable installation of host-identity by deleting the extracted binary.

```bash
Delete the extracted binary
```

--------------------------------

### Pre-push Checks

Source: https://github.com/dekobon/host-identity/blob/main/CONTRIBUTING.md

Format code, run clippy with strict warnings, and execute all tests before pushing changes.

```bash
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features --workspace
```

--------------------------------

### Upgrade host-identity with pkg (FreeBSD)

Source: https://github.com/dekobon/host-identity/blob/main/docs/install.md

Upgrade the host-identity package on FreeBSD using pkg.

```bash
sudo pkg upgrade ./host-identity-<ver>.pkg
```

--------------------------------

### Get host UUID (local sources)

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Print the host UUID using the default chain, which includes only local sources.

```bash
host-identity
```

--------------------------------

### Audit all host identity sources

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Walk through every source without short-circuiting, which is useful for diagnostics. Use the --format json flag for machine-readable output.

```bash
host-identity audit
```

```bash
host-identity audit --format json
```

--------------------------------

### Conventional Commit Message Format

Source: https://github.com/dekobon/host-identity/blob/main/docs/adding-an-identity-source.md

Example of a conventional commit message for adding a new source to the host-identity project. The scope is typically 'sources'.

```text
feat(sources): add <Provider> <kind> identity source
```

--------------------------------

### Audit All Host Identity Sources

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity/README.md

Iterates through all default sources to get every outcome, in chain order. Useful for operator tooling, diagnostics, or cross-validation.

```rust
// Every default source, every outcome, in chain order:
for outcome in host_identity::resolve_all() {
    println!("{:?} → {:?}", outcome.source(), outcome.host_id());
}

// Caller-chosen subset: use the same builder that feeds resolve().
use host_identity::Resolver;
use host_identity::sources::{MachineIdFile, DmiProductUuid};

let outcomes = Resolver::new()
    .push(MachineIdFile::default())
    .push(DmiProductUuid::default())
    .resolve_all();
```

--------------------------------

### Format and Lint host-identity Project

Source: https://github.com/dekobon/host-identity/blob/main/docs/developer-guide.md

Format the code using cargo fmt and run clippy for linting with warnings disabled. This ensures code style consistency and catches potential issues.

```bash
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
```

--------------------------------

### Resolve Host Identity UUID

Source: https://github.com/dekobon/host-identity/blob/main/README.md

Use the `resolve` function to get a stable UUID v5 for the host. This is the primary method for obtaining a host identity.

```rust
use host_identity::resolve;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let id = resolve()?;  // UUID v5 under a stable namespace
    println!("{id}");
    Ok(())
}
```

--------------------------------

### Extend Default Host Identity Resolver

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity/README.md

Starts with platform defaults and extends the resolver chain by prepending high-priority sources or appending fallback sources.

```rust
let id = Resolver::with_defaults()
    .prepend(my_high_priority_source)           // checked before defaults
    .push(FileOverride::new("/etc/fallback"))   // last-resort fallback
    .resolve()?;
```

--------------------------------

### List and View GitHub Release Workflows

Source: https://github.com/dekobon/host-identity/blob/main/docs/cutting-a-release.md

Use these commands to list recent release workflows and view logs for any failed runs.

```bash
gh run list --workflow=Release --limit 1
```

```bash
gh run view --log-failed
```

--------------------------------

### Watching the Release Pipeline

Source: https://github.com/dekobon/host-identity/blob/main/docs/cutting-a-release.md

Monitor the progress of the release pipeline using the GitHub CLI.

```bash
gh run watch
# or
gh run list --workflow=Release
```

--------------------------------

### Resolve All Sources with Caller-Chosen Subset

Source: https://github.com/dekobon/host-identity/blob/main/docs/algorithm.md

Use this to specify an exact set of sources to audit. Resolver::new() starts empty, so only sources explicitly pushed or prepended are included.

```rust
let outcomes = Resolver::new()
    .push(MachineIdFile::default())
    .push(DmiProductUuid::default())
    .push(some_custom_source)
    .resolve_all();

```

--------------------------------

### Fetch Public Minisign Key

Source: https://github.com/dekobon/host-identity/blob/main/docs/cutting-a-release.md

Fetch the public minisign key from the specific release tag to ensure verification against the correct key, not the latest from main.

```bash
TAG=v0.2.0
curl -fsSLO "https://raw.githubusercontent.com/dekobon/host-identity/${TAG}/minisign.pub"
```

--------------------------------

### Use StubTransport for Cloud Source Testing

Source: https://github.com/dekobon/host-identity/blob/main/docs/adding-an-identity-source.md

Example of using `StubTransport` to mock network responses for testing cloud metadata sources. This allows asserting requests and scripting responses.

```rust
use sources::cloud::test_support::StubTransport;

// Inside a test function:
let transport = StubTransport::new();
// ... script responses and assert captured requests ...
```

--------------------------------

### Verify Release Artifacts

Source: https://github.com/dekobon/host-identity/blob/main/docs/cutting-a-release.md

Perform manual verification of downloaded release artifacts using minisign for signature verification and sha256sum for checksum validation. Also, verify GitHub attestations.

```bash
TAG=v0.2.0
VERSION=0.2.0
minisign -Vm SHA256SUMS -p minisign.pub
```

```bash
TAG=v0.2.0
VERSION=0.2.0
grep "host-identity-${VERSION}-x86_64-unknown-linux-musl.tar.gz" SHA256SUMS | sha256sum -c
```

```bash
TAG=v0.2.0
VERSION=0.2.0
gh attestation verify "host-identity-${VERSION}-x86_64-unknown-linux-musl.tar.gz" \
  -R dekobon/host-identity
```

--------------------------------

### JSON output for host-identity audit

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Example of the JSON output when using 'host-identity audit --format json'. It includes the wrap strategy and a list of entries detailing each source's status.

```json
{
  "wrap": "v5",
  "entries": [
    { "source": "…", "status": "found", "uuid": "…", "error": null, "in_container": false }
  ]
}
```

--------------------------------

### Verify CLI Source Availability and Resolution

Source: https://github.com/dekobon/host-identity/blob/main/docs/adding-an-identity-source.md

Run these commands to confirm that new source identifiers are correctly registered and resolvable by the host-identity CLI tool.

```bash
cargo run -p host-identity-cli -- sources
cargo run -p host-identity-cli -- resolve --sources <your-id>
```

--------------------------------

### Get host UUID in JSON format

Source: https://github.com/dekobon/host-identity/blob/main/crates/host-identity-cli/README.md

Obtain the host UUID in JSON format using the --format json flag. The output is wrapped in an envelope indicating the active --wrap strategy.

```bash
host-identity resolve --format json
```