BlueBuild

https://github.com/blue-build/cli
Admin
BlueBuild is a CLI tool that builds Containerfiles and custom OCI images based on recipe.yml...
Tokens:101,708
Snippets:671
Trust Score:7.5
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Use blue-build-utils EnvString, Platform, Version, and syntax highlighting

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-misc.md

Shows how to use the blue-build-utils crate: expand and unexpand environment variables in EnvString, parse Platform and Version, access version major, get the default host platform, and syntax-highlight a string with the OceanDark theme. Requires the crate's features for env_str, platform, semver, and syntax_highlighting modules. The example prints the expanded and unexpanded strings, the platform architecture and variant, the major version, the host platform, and the highlighted output.

```rust
use blue_build_utils::{
    env_str::EnvString,
    platform::Platform,
    semver::Version,
    syntax_highlighting::{highlight_ser, DefaultThemes},
};

fn main() -> miette::Result<()> {
    std::env::set_var("TAG", "42-dev");
    let s = EnvString::from("ghcr.io/x/y:$TAG");
    println!("{}", s);              // ghcr.io/x/y:42-dev
    println!("{}", s.unexpanded()); // ghcr.io/x/y:$TAG

    let p: Platform = "linux/arm64".parse()?;
    println!("{} {}", p.arch(), p.variant().unwrap_or(""));

    let v: Version = "latest-42.20251020.1".parse()?;
    println!("{}", v.major); // 42

    let mut plat = Platform::default();
    println!("host platform: {plat}");

    let highlighted = highlight_ser(&s, "yml", Some(DefaultThemes::OceanDark))?;
    println!("{highlighted}");
    Ok(())
}
```

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

### Install BlueBuild CLI via Podman

Source: https://github.com/blue-build/cli/blob/main/README.md

Install the BlueBuild CLI binary to /usr/local/bin using Podman. The installer image is pulled automatically and removed after use.

```bash
podman run --pull always --rm ghcr.io/blue-build/cli:latest-installer | bash
```

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

### example

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/recipe-modules.md

Returns an example `Module` instance used in error messages.

```APIDOC
## `example`

### Description
Returns an example `Module` instance used in error messages.

### Method
N/A (Rust associated function)

### Signature
```rust
pub fn example() -> Self
```

### Parameters
None.

### Return Value
- `Module` - An example module.

### Example
```rust
let example_module = Module::example();
```

```

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

### Install BlueBuild CLI via GitHub Install Script

Source: https://github.com/blue-build/cli/blob/main/README.md

Install the BlueBuild CLI using the official GitHub install script. Downloads and executes the script directly from the repository.

```bash
bash <(curl -s https://raw.githubusercontent.com/blue-build/cli/main/install.sh)
```

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

### BlueBuild CLI command examples

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-misc.md

Common CLI commands for managing builds, authentication, pruning, and recipe upgrades.

```bash
bluebuild switch --reboot recipes/recipe.yml        # also: update|upgrade|rebase
bluebuild login ghcr.io -u octocat --password-stdin
bluebuild prune --all --volumes --force
bluebuild generate-iso image ghcr.io/user/image:latest -o out --variant silverblue
bluebuild completions zsh
bluebuild bug-report -r recipes/recipe.yml
bluebuild recipe upgrade recipes/recipe.yml          # feature "recipe-v2"
```

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

### CLI equivalents for init

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-init.md

CLI equivalents for the Rust examples: `bluebuild init` runs interactively in the current directory, while `bluebuild new` performs a non-interactive initialization with the same options as the first Rust snippet.

```bash
bluebuild init                    # interactive, in current dir
bluebuild new ./proj --image-name my-image --org-name my-org --registry ghcr.io \
  --ci-provider github --description "My image"
```

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

### Example usage of blue-build-utils

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-core.md

Demonstrates common utility functions including command existence checks, temporary directory creation, path generation, timestamp formatting, and retry logic.

```rust
use blue_build_utils::{
    check_command_exists, current_timestamp, generate_containerfile_path, get_tag_timestamp,
    retry, tempdir, tempdir_in,
};
use std::time::Duration;

fn main() -> miette::Result<()> {
    check_command_exists("podman")?; // Err if podman is missing

    let tmp = tempdir()?;                             // /tmp/bluebuild-tmp-XXXXXXXX…
    let nested = tempdir_in(tmp.path())?;             // inside tmp

    let containerfile = generate_containerfile_path("recipes/recipe.yml")?;
    println!("{}", containerfile.display());          // Containerfile.<b64-hash>

    println!("{}", get_tag_timestamp());              // 20260101
    println!("{}", current_timestamp());              // 2026-01-01T12:00:00Z

    let result = retry(3, Duration::from_secs(2), || {
        if std::env::var("READY").is_ok() {
            Ok(42)
        } else {
            Err(miette::miette!("not ready"))
        }
    });
    Ok(())
}
```

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

### Install BlueBuild CLI with Cargo

Source: https://github.com/blue-build/cli/blob/main/README.md

Install the BlueBuild CLI via Cargo, which allows building for your specific environment. This is the recommended installation method.

```bash
cargo install --locked blue-build
```

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

### Module methods: get_modules, get_from_file_path, example

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/recipe-modules.md

Provides methods on `Module`: `get_modules` recursively resolves `from-file` modules and errors on circular dependencies or improper format; `get_from_file_path` resolves `from_file` against `./recipes`; `example` returns a `script` module example used in error messages.

```rust
impl Module {
    /// Get's any child modules.
    ///
    /// # Errors
    /// Will error if the module cannot be
    /// deserialized or the user uses another
    /// property alongside `from-file:`.
    pub fn get_modules(modules: &[Self], traversed_files: Option<Vec<PathBuf>>) -> Result<Vec<Self>> { ... }

    #[must_use]
    pub fn get_from_file_path(&self) -> Option<PathBuf> { ... }

    #[must_use]
    pub fn example() -> Self { ... }
}

```

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

### Implement Credentials with init and get methods

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-misc.md

Shows the implementation block for Credentials, including the init method that sets credentials and the get method that retrieves them. Both methods may panic if the mutex cannot be locked.

```rust
impl Credentials {
    /// Set the users credentials for the current set of actions.
    ///
    /// # Panics
    /// Will panic if it can't lock the mutex.
    pub fn init(args: CredentialsArgs) { ... }

    /// Get the credentials for the current set of actions.
    ///
    /// # Panics
    /// Will panic if it can't lock the mutex.
    #[must_use]
    pub fn get(registry: &str) -> Option<Self> { ... }
}
```

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

### Example usage of ImageRef, Tag, and OciRef

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-container.md

Shows how to parse a reference, create an ImageRef, append a tag, and construct OCI archive and directory references. The example prints the resulting values, including the platform-specific tag suffix and the oci-archive/oci prefixes.

```rust
use blue_build_utils::container::{ImageRef, OciRef, Tag};
use blue_build_utils::platform::Platform;
use oci_client::Reference;

fn main() -> miette::Result<()> {
    let ref_: Reference = "ghcr.io/foo/bar:latest".parse()?;

    let remote: ImageRef = ImageRef::from(&ref_);
    let amd64 = remote.with_platform(Platform::LinuxAmd64);
    println!("{amd64}"); // ghcr.io/foo/bar:latest_linux/amd64 (displayed raw)

    let tag: Tag = "42".parse()?;
    let tagged = amd64.append_tag(&tag);
    println!("{tagged:?}");

    let tar: ImageRef = ImageRef::from(std::path::Path::new("out/my-img.tar.gz"));
    println!("{tar}"); // oci-archive:out/my-img.tar.gz

    let oci = OciRef::from_oci_directory("oci-out")?;
    println!("{}", oci.to_os_string().to_string_lossy()); // oci:oci-out
    Ok(())
}
```

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

### Automatic initialization with InitCommand

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-init.md

Initializes a new project non-interactively by providing all required options through the builder. The example sets image name, organization, registry, description, CI provider, and git initialization, then runs the command on the specified directory.

```rust
use blue_build::commands::{BlueBuildCommand, init::InitCommand, init::NewInitCommon, init::CiProvider};
use bon::Builder;

fn main() -> miette::Result<()> {
    let common = NewInitCommon::builder()
        .image_name("my-image")
        .org_name("my-org")
        .registry("ghcr.io")
        .description("A custom image")
        .ci_provider(CiProvider::Github)
        .no_git(false)
        .build();

    InitCommand::builder()
        .dir("my-project".into())
        .common(common)
        .build()
        .try_run()
}
```

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

### Install BlueBuild CLI via Docker

Source: https://github.com/blue-build/cli/blob/main/README.md

Install the BlueBuild CLI binary to /usr/local/bin using Docker. The installer image is pulled automatically and removed after use.

```bash
docker run --pull always --rm ghcr.io/blue-build/cli:latest-installer | bash
```

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

### Example usage of Chunkah builder

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-implementations.md

Shows how to build a Chunkah instance with a maximum of 64 layers and tag 'latest', then check driver requirements and initialize a runner. The commented line indicates how to run post_build with PostBuildOpts.

```rust
use blue_build_process_management::drivers::{
    Chunkah, PodmanDriver, PostBuild, PostBuildRunner,
    opts::PostBuildOpts,
};
use oci_client::Reference;

fn main() -> miette::Result<()> {
    let chunkah = Chunkah::builder()
        .max_layers(std::num::NonZeroU32::new(64).unwrap())
        .tag("latest")
        .build();
    chunkah.check_driver_requirements()?; // errors unless build driver is Podman

    let runner = chunkah.init()?;
    // runner.post_build(PostBuildOpts::builder()...build()) would run chunkah
    Ok(())
}
```

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

### CLI equivalents for generate and template

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-generate.md

Command-line equivalents for the `GenerateCommand` examples. Includes `bluebuild generate`, `bluebuild template` (visible alias), and `bluebuild generate --display-full-recipe` with a syntax theme.

```bash
bluebuild generate -o Containerfile recipes/recipe.yml
bluebuild template recipes/recipe.yml             # 'template' is a visible alias
bluebuild generate --display-full-recipe -t solarized-dark recipes/recipe.yml
```

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

### Install bash completions with bluebuild completions

Source: https://github.com/blue-build/cli/blob/main/README.md

Generates bash completions and stores them for user or system-wide integration. Requires bash-completion installed. Subsequent invocations of bluebuild will respond to <Tab> autocompletions.

```bash
# user completions
$ bluebuild completions bash > ~/.local/share/bash-completion/completions/bluebuild
# system-wide completions
$ bluebuild completions bash | sudo tee /usr/share/bash-completion/completions/bluebuild
```

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

### Initialize Driver and Get Image Metadata

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-types.md

Initializes the driver with Podman as the build driver and Sigstore for signing, then retrieves and prints image metadata for a given reference. The CI driver is determined from the runtime environment (Local/Github/Gitlab). The metadata digest and all digests are printed, and the version is extracted with error handling for missing or invalid version labels.

```rust
use blue_build_process_management::drivers::{
    Driver, DriverArgs, InspectDriver,
    opts::GetMetadataOpts,
    types::{BuildDriverType, CiDriverType, SigningDriverType},
};

fn main() -> miette::Result<()> {
    Driver::init(
        DriverArgs::builder()
            .build_driver(BuildDriverType::Podman)
            .signing_driver(SigningDriverType::Sigstore)
            .build(),
    );

    // Driver::get_ci_driver() reflects the runtime env (Local/Github/Gitlab)
    println!("{:?}", Driver::get_ci_driver());

    let ref_: oci_client::Reference = "ghcr.io/ublue-os/silverblue-main:latest".parse()?;
    let md = Driver::get_metadata(GetMetadataOpts::builder().image(&ref_).build())?;
    println!("digest: {}", md.digest());
    println!("all digests: {:?}", md.all_digests());

    match md.get_version() {
        Ok(v) => println!("version major: {}", v.major),
        Err(e) => println!("{e:?}"), // "No version label found" or parse failure
    }
    Ok(())
}
```

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

### InitCommand try_run with empty-directory check

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-init.md

Implements `BlueBuildCommand::try_run` for `InitCommand`. Initializes drivers, resolves the target directory (defaulting to the current working directory), and bails with `Must be in an empty directory!` if the directory exists and is non-empty. Otherwise proceeds to the private `start` pipeline.

```rust
fn try_run(&mut self) -> Result<()> {
    Driver::init(self.common.drivers);
    let base_dir = self.dir.get_or_insert(env::current_dir().into_diagnostic()?);
    if base_dir.exists() && fs::read_dir(base_dir).is_ok_and(|dir| dir.count() != 0) {
        bail!("Must be in an empty directory!");
    }
    self.start(&self.questions()?)
}
```

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

### Install BlueBuild on Non-NixOS via Nix Flake

Source: https://github.com/blue-build/cli/blob/main/README.md

Install BlueBuild globally on non-NixOS systems using the Nix flake from Flakehub. Replace the '*' with a specific tag if desired.

```shell
# you can replace "*" with a specific tag
nix profile install https://flakehub.com/f/blue-build/cli/*.tar.gz#bluebuild
```

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

### Rebase to unsigned and signed image with reboot steps

Source: https://github.com/blue-build/cli/blob/main/integration-tests/empty-files-repo/README.md

First rebase to the unsigned image to install signing keys, reboot, then rebase to the signed image and reboot again. The 'latest' tag points to the latest build, which uses the Fedora version in recipe.yml.

```bash
rpm-ostree rebase ostree-unverified-registry:cli/blue-build/test-empty-files:latest
```

```bash
systemctl reboot
```

```bash
rpm-ostree rebase ostree-image-signed:docker://cli/blue-build/test-empty-files:latest
```

```bash
systemctl reboot
```

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

### bluebuild build CLI: push and chunkah variants

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-build.md

CLI equivalents for the two Rust examples: one with push, retry, and archive options; the other with chunkah, base image removal, and compression format.

```bash
bluebuild build --push --registry-namespace my-org --retry-push --retry-count 3 --archive out recipes/recipe.yml
bluebuild build --chunkah --chunkah-version v0.2.0 --remove-base-image --compression-format zstd recipes/recipe.yml
```

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

### Build and run containers with Driver and BuildOpts/RunOpts

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-opts.md

Shows how to use the `Driver` trait to build a container image and run a container with the `blue_build_process_management` crate. The example builds an image from a `Containerfile` for the Linux/amd64 platform with squash enabled, then runs an `alpine:latest` container with arguments and environment variables, removing it after execution. The exit status is printed to stdout.

```rust
use blue_build_process_management::drivers::{
    BuildDriver, Driver, opts::{BuildOpts, BuildTagPushOpts, RunOpts},
};
use blue_build_process_management::run_envs;
use blue_build_utils::container::ImageRef;

fn main() -> miette::Result<()> {
    let image: ImageRef = ImageRef::from(&"ghcr.io/me/img:latest".parse::<oci_client::Reference>()?);

    Driver::build(
        BuildOpts::builder()
            .image(&image)
            .containerfile(std::path::Path::new("Containerfile"))
            .platform(Some(blue_build_utils::platform::Platform::LinuxAmd64))
            .squash(true)
            .build(),
    )?;

    let status = Driver::run(
        RunOpts::builder()
            .image("alpine:latest")
            .args(&["echo".to_owned(), "hi".to_owned()])
            .env_vars(&run_envs!["FOO" => "bar"])
            .remove(true)
            .build(),
    )?;
    println!("exit: {status}");
    Ok(())
}
```

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

### Error handling for InitCommand

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-init.md

Shows how to handle errors when initializing in a non-empty directory. The command returns a Result; on error, the example prints the error and exits with code 1, with comments noting possible failures like "Must be in an empty directory!" or a git error.

```rust
use blue_build::commands::{BlueBuildCommand, init::InitCommand, init::NewInitCommon};
use bon::Builder;

fn main() {
    let cmd = InitCommand::builder()
        .dir("/non/empty/dir".into())
        .common(NewInitCommon::default())
        .build()
        .try_run();

    match cmd {
        Ok(()) => {}
        Err(e) => {
            // e.g. "Must be in an empty directory!" or a git failure
            eprintln!("{e:?}");
            std::process::exit(1);
        }
    }
}
```

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

### BlueBuildCommand try_run implementation

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-validate.md

Entry point of the validate command. It errors if the recipe file does not exist, blocks on async validator setup, validates the recipe, and logs a success message. The `...` placeholder indicates omitted error-handling code in the source.

```rust
fn try_run(&mut self) -> miette::Result<()> {
    if !self.recipe.is_file() {
        bail!("File {recipe_path_display} must exist");
    }
    ASYNC_RUNTIME.block_on(self.setup_validators()).wrap_err("Failed to setup validators")?;
    if let Err(errors) = self.validate_recipe() { ... }
    info!("Recipe {recipe_path_display} is valid");
    Ok(())
}
```

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

### Render Containerfile to stdout with custom theme

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-generate.md

Example usage of `GenerateCommand` to render a Containerfile to stdout with a custom syntax theme. Uses `DefaultThemes::SolarizedDark` and sets registry and namespace.

```rust
use blue_build::commands::{BlueBuildCommand, generate::GenerateCommand};
use blue_build_utils::syntax_highlighting::DefaultThemes;
use bon::Builder;

fn main() -> miette::Result<()> {
    let mut cmd = GenerateCommand::builder()
        .recipe("recipes/recipe.yml".into())
        .registry("ghcr.io")
        .registry_namespace("my-org")
        .syntax_theme(DefaultThemes::SolarizedDark)
        .build();
    cmd.try_run()?;
    Ok(())
}
```

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

### Basic CLI invocations

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/cli.md

Shows basic CLI invocations: building with push and registry options, generating a Containerfile, and installing bash completions. The build command uses --no-log-filter and -vv for verbose output.

```bash
bluebuild --no-log-filter -vv build --push --registry ghcr.io --username me recipes/recipe.yml
bluebuild generate -o Containerfile recipes/recipe.yml
bluebuild completions bash > ~/.local/share/bash-completion/completions/bluebuild
```

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

### Initialize Ctrl-C handler with pub fn init

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/process.md

Initializes the signal handler at the start of a binary. This function will panic if called more than once.

```rust
/// Initialize Ctrl-C handler. This should be done at the start
/// of a binary.
///
/// # Panics
/// Will panic if initialized more than once.
pub fn init<F>(app_exec: F)
where
    F: FnOnce() + Send + 'static,
{ ... }
```

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

### Tab completion output for bluebuild

Source: https://github.com/blue-build/cli/blob/main/README.md

Shows the output of pressing <Tab> after `bluebuild` when completions are installed. Lists available commands and flags.

```bash
$ bluebuild # press <Tab>
-v           -V           --help       template     bug-report
-q           --verbose    --version    upgrade      completions
-h           --quiet      build        rebase       help
```

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

### Copy file from build context using copy module

Source: https://github.com/blue-build/cli/blob/main/template/templates/modules/copy/README.md

Omit `from` to copy from the build context. This example copies `file/to/copy.conf` to `/usr/etc/app/`. The generated Dockerfile instruction uses `COPY --linked`.

```yaml
modules:
- type: copy
  src: file/to/copy.conf
  dest: /usr/etc/app/

```

```dockerfile
COPY --linked file/to/copy.conf /usr/etc/app/

```

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

### Driver facade usage example

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-traits.md

Shows how to use the public driver traits without requiring trait objects, calling get_metadata on the concrete OciClientDriver. Parses an image reference and prints the digest from the returned metadata.

```rust
use blue_build_process_management::drivers::{
    BuildDriver, InspectDriver, CiDriver,
    opts::{BuildOpts, GetMetadataOpts, GenerateTagsOpts},
    types::BuildDriverType,
};

fn main() -> miette::Result<()> {
    // All callable on the concrete driver struct too:
    let base: oci_client::Reference = "ghcr.io/ublue-os/silverblue-main:latest".parse()?;
    let md = blue_build_process_management::drivers::OciClientDriver::get_metadata(
        GetMetadataOpts::builder().image(&base).build(),
    )?;
    println!("{}", md.digest());
    Ok(())
}

```

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

### Copy file from an image using copy module

Source: https://github.com/blue-build/cli/blob/main/template/templates/modules/copy/README.md

Use the `copy` module with `from`, `src`, and `dest` to copy a file from an external image. This example copies `/usr/bin/yq` from `docker.io/mikefarah/yq` into `/usr/bin/`. The generated Dockerfile instruction uses `COPY --linked`.

```yaml
modules:
- type: copy
  from: docker.io/mikefarah/yq
  src: /usr/bin/yq
  dest: /usr/bin/

```

```dockerfile
COPY --linked --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/

```

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

### DetachedContainer::start

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/process.md

Runs the provided command to start a container with the given signal ID, taking the output of the command as the container ID. Returns an error if the command fails or if the output is invalid UTF-8.

```APIDOC
## DetachedContainer::start

### Description
Runs the provided command to start a container with the given signal ID, taking the output of the command as the container ID. Returns an error if the command fails or if the output is invalid UTF-8.

### Method
start

### Signature
`pub fn start(signal_id: ContainerSignalId, mut cmd: Command) -> Result<Self>`

### Parameters
- **signal_id** (ContainerSignalId) - Required - The signal ID containing the cid path and runtime configuration.
- **cmd** (Command) - Required - The command to run to start the container.

### Behavior
- Registers the cid, runs `cmd`, bails `"Failed to start detached container image.\nstderr: ..."` on failure, trims whitespace from stdout to obtain the `ContainerId`.

### Errors
Returns an error if the command fails or if the output of the command is invalid UTF-8.

### Returns
`Result<Self>` - A `DetachedContainer` instance on success.
```

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

### Implement DockerDriver inherent methods

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-implementations.md

Inherent methods for DockerDriver: setup() ensures a buildx builder named 'bluebuild' exists, and has_buildx() checks if Docker Buildx is available.

```rust
impl DockerDriver {
    fn setup() -> Result<()> { ... }

    #[must_use]
    pub fn has_buildx() -> bool { ... }
}
```

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

### Resolve recipe full contents and write to file

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-generate.md

Example usage of `GenerateCommand` to resolve a recipe's full contents (debug `from-file` resolution) and write to file. Uses `display_full_recipe(true)`, `output("resolved.yml")`, and `skip_validation(true)`. On error, prints the miette report and exits with code 1.

```rust
use blue_build::commands::{BlueBuildCommand, generate::GenerateCommand};
use bon::Builder;

fn main() -> miette::Result<()> {
    let mut cmd = GenerateCommand::builder()
        .recipe("recipes/recipe.yml".into())
        .display_full_recipe(true)
        .output("resolved.yml".into())
        .skip_validation(true) // already validated elsewhere
        .build();

    if let Err(e) = cmd.try_run() {
        eprintln!("{e:?}"); // miette report; e.g. schema fetch failure
        std::process::exit(1);
    }
    Ok(())
}
```

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

### current_timestamp

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-core.md

Gets the current UTC timestamp in ISO 8601 format.

```APIDOC
## `current_timestamp`

### Description
Returns the current UTC timestamp in ISO 8601 format.

### Signature
```rust
pub fn current_timestamp() -> String
```

### Returns
- **`String`** - The current UTC timestamp in `YYYY-MM-DDTHH:MM:SSZ` format.

### Example
```rust
println!("{}", current_timestamp());
```
```

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

### get_env_var function signature

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-core.md

Gets an environment variable, wrapping errors with a miette error.

```rust
/// Get's the env var wrapping it with a miette error
///
/// # Errors
/// Will error if the env var doesn't exist.
pub fn get_env_var(key: &str) -> Result<String> { ... }
```

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

### get_tag_timestamp

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-core.md

Gets the current timestamp in YYYYMMDD format for build tags.

```APIDOC
## `get_tag_timestamp`

### Description
Returns the current timestamp in `YYYYMMDD` format for tagging.

### Signature
```rust
pub fn get_tag_timestamp() -> String
```

### Returns
- **`String`** - The current date in `YYYYMMDD` format.

### Example
```rust
println!("{}", get_tag_timestamp());
```
```

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

### Initialize Drivers and Perform Image Operations

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-facade.md

Demonstrates initializing the Driver with default settings or specific build/run drivers, followed by retrieving OS versions and generating image names.

```rust
use blue_build_process_management::drivers::{
    Driver, DriverArgs,
    opts::{GenerateImageNameOpts, GenerateTagsOpts, GetMetadataOpts},
    types::{BuildDriverType, RunDriverType},
};

fn main() -> miette::Result<()> {
    // Option 1: let Driver pick
    Driver::init(DriverArgs::default());

    // Option 2: force podman for build+run
    Driver::init(
        DriverArgs::builder()
            .build_driver(BuildDriverType::Podman)
            .run_driver(RunDriverType::Podman)
            .build(),
    );

    let os_version = Driver::get_os_version()
        .oci_ref(&"ghcr.io/ublue-os/silverblue-main:latest".parse()?)
        .call()?;
    println!("os version: {os_version}");

    let name = Driver::generate_image_name(
        GenerateImageNameOpts::builder()
            .name("my-image")
            .maybe_registry(Some("ghcr.io"))
            .maybe_registry_namespace(Some("me"))
            .build(),
    )?;
    println!("{name}");
    Ok(())
}
```

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

### Build and boot locally with bluebuild switch

Source: https://github.com/blue-build/cli/blob/main/README.md

Builds and boots an image locally using an oci-archive tarball. Can be run as a normal user; sudo is only requested when moving the archive into /etc/bluebuild. Add --reboot/-r to restart immediately.

```bash
bluebuild switch recipes/recipe.yml
```

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

### FromFileList trait: get from-file paths

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/recipe-core.md

Public trait implemented by ModuleExt and StagesExt. Provides a default implementation for get_module_from_file_paths that returns an empty vector, while get_from_file_paths must be implemented.

```rust
pub trait FromFileList {
    const LIST_KEY: &str;

    fn get_from_file_paths(&self) -> Vec<PathBuf>;

    fn get_module_from_file_paths(&self) -> Vec<PathBuf> {
        Vec::new()
    }
}
```

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

### DetachedContainer struct definition and implementation

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/process.md

Defines the DetachedContainer structure for managing detached containers, including methods to start containers and automatic cleanup via the Drop trait.

```rust
#[derive(Debug, PartialEq, Eq)]
pub struct DetachedContainer {
    signal_id: ContainerSignalId,
    container_id: ContainerId,
}

impl DetachedContainer {
    /// Runs the provided command to start a container with the given signal ID,
    /// taking the output of the command as the container ID.
    ///
    /// # Errors
    /// Returns an error if the command fails or if the output of the command
    /// is invalid UTF-8.
    pub fn start(signal_id: ContainerSignalId, mut cmd: Command) -> Result<Self> { ... }

    #[must_use]
    pub const fn id(&self) -> &ContainerId { &self.container_id }

    #[must_use]
    pub fn cid_path(&self) -> &Path { &self.signal_id.cid_path }
}

impl Drop for DetachedContainer {
    fn drop(&mut self) {
        if kill_container(&self.signal_id).is_ok_and(|exit_status| exit_status.success()) {
            remove_cid(&self.signal_id);
        }
    }
}
```

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

### Driver::init

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-facade.md

Initializes the Strategy with user provided credentials. Must be called before using any strategies. Panics if unable to initialize drivers.

```APIDOC
## `Driver::init`

### Description
Initializes the Strategy with user provided credentials. If you want to take advantage of a user's credentials, run init before trying to use any of the strategies. Panics if unable to initialize drivers.

### Method
`Driver::init`

### Parameters
- `args` (`DriverArgs`) - Required - Driver selections

### Behavior
Idempotent (guarded by `static INIT: AtomicBool` — only the first call runs `determine_driver`). Warns when `inspect_driver` is explicitly set (deprecated). Each selected driver goes through `DetermineDriver::determine_driver`, which panics with a version-requirements message if no suitable binary is found (e.g. docker ≥23 with buildx, podman ≥4, or buildah ≥1.29).
```

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

### DriverVersion trait definition

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-traits.md

Sealed trait for version checking. VERSION_REQ is a semver requirement (e.g. Docker ">=23", Podman ">=4", Buildah ">=1.29", Cosign ">=2"). version() runs `<tool> version --json` (or `-f json`) and parses; is_supported_version() is provided and returns whether the installed version satisfies VERSION_REQ.

```rust
#[expect(private_bounds)]
pub trait DriverVersion: PrivateDriver {
    /// The version req string slice that follows
    /// the semver standard <https://semver.org/>.
    const VERSION_REQ: &'static str;

    /// Returns the version of the driver.
    ///
    /// # Errors
    /// Will error if it can't retrieve the version.
    fn version() -> Result<Version>;

    #[must_use]
    fn is_supported_version() -> bool {
        Self::version().is_ok_and(|version| {
            VersionReq::parse(Self::VERSION_REQ).is_ok_and(|req| req.matches(&version))
        })
    }
}

```

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

### BuildChunkedOciDriver trait: build_chunked_oci and build_rechunk_tag_push

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-traits.md

Defines the sealed BuildChunkedOciDriver trait for building chunked OCI images. The provided build_chunked_oci method pulls a previous build as the layer-plan baseline (unless opts.clear_plan), then runs rpm-ostree compose build-chunked-oci with the specified flags inside the runner context and cleans up the previous image ID. The provided build_rechunk_tag_push method builds each platform to <image>_<platform>_unchunked, optionally removes the base image and prunes volumes, starts an RpmOstreeRunner, rechunks serially, retags to platform-tagged refs, creates/pushes manifests (pushed twice for a podman layer-annotation bug workaround), and returns the image list.

```rust
pub trait BuildChunkedOciDriver: BuildDriver + ImageStorageDriver {
    fn manifest_create_with_runner(runner: &RpmOstreeRunner, opts: ManifestCreateOpts) -> Result<()>;
    fn manifest_push_with_runner(runner: &RpmOstreeRunner, opts: ManifestPushOpts) -> Result<()>;
    fn pull_with_runner(runner: &RpmOstreeRunner, opts: PullOpts) -> Result<ContainerId>;
    fn remove_image_with_runner(runner: &RpmOstreeRunner, image_ref: &str) -> Result<()>;
    fn build_chunked_oci(
        runner: &RpmOstreeRunner,
        unchunked_image: &ImageRef<'_>,
        final_image: &ImageRef<'_>,
        opts: BuildChunkedOciOpts,
    ) -> Result<()> { ... }
    fn build_rechunk_tag_push(opts: BuildRechunkTagPushOpts) -> Result<Vec<String>> { ... }
}
```

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

### RpmOstreeDriver struct definition

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-implementations.md

Defines the RpmOstreeDriver struct, which implements BootDriver. Its status method runs `rpm-ostree status --json` and deserializes into a Status boxed as dyn BootStatus, bailing with "Failed to get `rpm-ostree` status!" on failure. switch runs `rpm-ostree rebase ostree-unverified-image:containers-storage:<image> [--reboot]` using the constant OSTREE_UNVERIFIED_IMAGE, and upgrade runs `rpm-ostree upgrade [--reboot]`.

```rust
pub struct RpmOstreeDriver;
```

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

### DetermineDriver trait definition

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-traits.md

Sealed trait contract for selecting a driver. Implemented for Option<BuildDriverType>, Option<RunDriverType>, Option<SigningDriverType>, Option<CiDriverType>, Option<BootDriverType>, and Option<InspectDriverType>. If the Option is None, it probes installed binaries; otherwise it returns the enclosed value.

```rust
#[expect(private_bounds)]
pub trait DetermineDriver<T>: PrivateDriver {
    fn determine_driver(&mut self) -> T;
}

```

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

### Driver::init method

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-facade.md

Initializes the strategy with user-provided credentials. This method is idempotent and will panic if it is unable to initialize drivers.

```rust
#[bon]
impl Driver {
    /// Initializes the Strategy with user provided credentials.
    ///
    /// If you want to take advantage of a user's credentials,
    /// you will want to run init before trying to use any of
    /// the strategies.
    ///
    /// # Panics
    /// Will panic if it is unable to initialize drivers.
    pub fn init(mut args: DriverArgs) { ... }
    ...
}
```

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

### Library-style usage with builder API

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/cli.md

Library-style usage: initializes drivers with Driver::init (idempotent, auto-detects docker/podman/buildah) and builds a BuildCommand via the bon builder API. The main function calls try_run() on the built command.

```rust
use blue_build::commands::{BuildCommand, BlueBuildCommand};
use blue_build_process_management::drivers::{Driver, DriverArgs};

fn main() -> miette::Result<()> {
    // Initialize drivers up front (idempotent; auto-detects docker/podman/buildah)
    Driver::init(DriverArgs::default());

    build_with_builder().try_run() // uses the builder API from bon
}

fn build_with_builder() -> BuildCommand {
    use bon::Builder;
    BuildCommand::builder()
        .recipe(vec!["recipes/recipe.yml".into()])
        .push(false)
        .squash(false)
        .no_sign(true)
        .skip_validation(true)
        .build()
}
```

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

### Render Containerfile with `ContainerFileTemplate`

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/template.md

Shows how to render a Containerfile programmatically, exactly what `GenerateCommand` does. It parses a recipe, builds a `ContainerFileTemplate` with required fields, renders it, and prints the result.

```rust
use blue_build_recipe::{Recipe, RecipeGetters};
use blue_build_template::{BuildEngine, ContainerFileTemplate, Template};
use blue_build_utils::current_timestamp;
use std::collections::BTreeMap;

fn main() -> miette::Result<()> {
    let recipe = Recipe::parse("recipes/recipe.yml")?;
    let labels = BTreeMap::from([(
        "org.opencontainers.image.created".to_string(),
        current_timestamp(),
    )]);

    let template = ContainerFileTemplate::builder()
        .os_version(41u64)
        .build_id(uuid::Uuid::new_v4())
        .recipe(&recipe)
        .recipe_path(std::path::Path::new("recipes/recipe.yml"))
        .registry("ghcr.io/my-org")
        .build_scripts_dir(std::path::Path::new(".bluebuild-scripts_abc"))
        .base_digest("sha256:0000...")
        .build_features(&["bootc".to_string()])
        .build_engine(BuildEngine::Oci)
        .labels(&labels)
        .build();

    let containerfile = template.render()?;
    println!("{containerfile}");
    Ok(())
}
```

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

### fn main() in src/bin/bluebuild.rs

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/cli.md

Sets up miette error handling, logging, and dispatches to subcommand implementations.

```rust
fn main() {
    let args = BlueBuildArgs::parse();

    miette::set_hook(Box::new(|_| {
        Box::new(
            miette::MietteHandlerOpts::new()
                .terminal_links(true)
                .footer(format!(concat!(
                    "Try running with `{arg}` for trace logging.\n",
                    "You can also open an issue at https://github.com/blue-build/cli/issues"
                ), arg = "-vv".bright_yellow()))
                .context_lines(3)
                .tab_width(4)
                .wrap_lines(false)
                .with_cause_chain()
                .show_related_errors_as_nested()
                .build(),
        )
    }))
    .expect("Miette hook should be set");

    Logger::new()
        .filter_level(args.verbosity.log_level_filter())
        .filter_modules(if args.no_log_filter {
            vec![]
        } else {
            vec![
                ("hyper::proto", LevelFilter::Off),
                ("hyper_util", LevelFilter::Off),
                ("reqwest", LevelFilter::Off),
                ("oci_client", LevelFilter::Off),
                ("rustls", LevelFilter::Off),
                ("mio", LevelFilter::Off),
            ]
        })
        .log_out_dir(args.log_out.clone())
        .init();

    signal_handler::init(|| match args.command {
        CommandArgs::Build(mut command) => command.run(),
        CommandArgs::Generate(mut command) => command.run(),
        CommandArgs::Switch(mut command) => command.run(),
        CommandArgs::Login(mut command) => command.run(),
        CommandArgs::New(mut command) => command.run(),
        CommandArgs::Init(mut command) => command.run(),
        CommandArgs::GenerateIso(mut command) => command.run(),
        CommandArgs::Validate(mut command) => command.run(),
        CommandArgs::Prune(mut command) => command.run(),
        CommandArgs::BugReport(mut command) => command.run(),
        CommandArgs::Completions(mut command) => command.run(),
        #[cfg(feature = "recipe-v2")]
        CommandArgs::Recipe(mut command) => command.run(),
    });
}
```

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

### BuildOpts struct

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-opts.md

Options for building container images. Required fields are image and containerfile. Optional fields include base_image, squash, platform, host_network, privileged, cache_from, cache_to, and secrets. Defaults are false for booleans and None for options.

```rust
#[derive(Debug, Clone, Copy, Builder)]
#[builder(derive(Debug, Clone))]
pub struct BuildOpts<'scope> {
    pub image: &'scope ImageRef<'scope>,
    /// Base image to pull before building
    pub base_image: Option<&'scope Reference>,
    #[builder(default)]
    pub squash: bool,
    pub containerfile: &'scope Path,
    pub platform: Option<Platform>,
    #[builder(default)]
    pub host_network: bool,
    #[builder(default)]
    pub privileged: bool,
    pub cache_from: Option<&'scope Reference>,
    pub cache_to: Option<&'scope Reference>,
    #[builder(default)]
    pub secrets: &'scope [&'scope Secret],
}
```

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

### BuildCommand builder: basic build with push and signing

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-build.md

Builds a recipe with push and signing enabled, using the builder pattern. Sets retry options, archive output, and disables signing. The try_run method returns a miette::Result that propagates errors.

```rust
use blue_build::commands::{BlueBuildCommand, build::BuildCommand};
use bon::Builder;

fn main() -> miette::Result<()> {
    let mut cmd = BuildCommand::builder()
        .recipe(vec!["recipes/recipe.yml".into()])
        .push(true)
        .registry_namespace("my-org")
        .retry_push(true)
        .retry_count(3)
        .archive("out".into())          // also write ./out/<name>.tar.gz
        .no_sign(true)                  // skip cosign
        .build();
    cmd.try_run()?;                     // propagates miette::Report
    Ok(())
}
```

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

### Build image with bluebuild build

Source: https://github.com/blue-build/cli/blob/main/README.md

Builds an image directly from a recipe file, templating it and building with docker, podman, or buildah. This command hides the template details.

```bash
bluebuild build ./recipes/recipe.yml
```

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

### TryFrom implementation for ImageMetadata

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-types.md

Alternate construction of `ImageMetadata` from docker `Metadata` and optional `Platform`. Errors: `"Image information does not exist for {platform}"` when multi-arch config missing the platform, and `"Manifest does not exist for {platform}"` when no matching architecture in manifest list. This `ImageMetadata` is a different same-named struct in the docker metadata module with `labels` and `digest` fields.

```rust
impl TryFrom<(Metadata, Option<Platform>)> for ImageMetadata {
    type Error = Report;
    fn try_from((metadata, platform): (Metadata, Option<Platform>)) -> Result<Self, Self::Error> { ... }
}
```

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

### SwitchCommand programmatic usage

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/commands-misc.md

Demonstrates how to construct and run a SwitchCommand using the builder pattern.

```rust
use blue_build::commands::{
    BlueBuildCommand,
    login::LoginCommand,
    prune::PruneCommand,
    switch::SwitchCommand,
};
use bon::Builder;

fn do_switch() -> miette::Result<()> {
    SwitchCommand::builder()
        .recipe("recipes/recipe.yml".into())
        .reboot(false)
        .skip_validation(false)
        .build()
        .try_run()
}
```

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

### Generate Containerfile with bluebuild generate

Source: https://github.com/blue-build/cli/blob/main/README.md

Generates a Containerfile from a recipe file. The output path is specified with -o and the recipe file is given as an argument. Further options are available via `bluebuild template --help`.

```bash
bluebuild generate -o <CONTAINERFILE> <RECIPE_FILE>
```

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

### containerfile module with containerfiles

Source: https://github.com/blue-build/cli/blob/main/template/templates/modules/containerfile/README.md

Tells the compiler to include Containerfiles from the ./containerfiles/ directory. The compiler looks for ./containerfiles/example/Containerfile and ./containerfiles/subroutine/Containerfile. Each included Containerfile's instructions become separate layers.

```yaml
modules:
  - type: containerfile
    containerfiles:
      - example
      - subroutine
```

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

### Run BlueBuild via Distrobox

Source: https://github.com/blue-build/cli/blob/main/README.md

Run BlueBuild inside a Distrobox container using the provided Alpine image. This exports the bluebuild command to your host, but the container is rootless, so you cannot use this method to locally rebase to an image.

```bash
distrobox assemble create
```

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

### highlight

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/utils-misc.md

Highlights a file's contents with syntax highlighting using the syntect library. When stdout is a terminal, it applies syntax highlighting with a custom embedded Dockerfile syntax set and returns 24-bit ANSI output. When stdout is not a terminal, it returns the file contents unchanged.

```APIDOC
## [FUNCTION] highlight

### Description
Highlights a file's contents with syntax highlighting using the syntect library. When stdout is a terminal, it applies syntax highlighting with a custom embedded Dockerfile syntax set and returns 24-bit ANSI output. When stdout is not a terminal, it returns the file contents unchanged.

### Method
FUNCTION

### Endpoint
`blue_build_utils::syntax_highlighting::highlight`

### Parameters
#### Parameters
- **file** (`&str`) - Required - The file contents to highlight.
- **file_type** (`&str`) - Required - The file type or extension used to determine the syntax.
- **theme** (`Option<DefaultThemes>`) - Optional - The theme to use for highlighting. If `None`, the default theme is used.

### Return Value
- **Result<String>** - A `miette::Result<String>` containing the highlighted string, or an error if the theme or syntax is unknown.

### Errors
- `"Failed to get highlight theme"` - Returned when the provided theme is unknown.
- `"Failed to get syntax"` - Returned when the syntax for the given file type is unknown.

### Example
```rust
let highlighted = highlight("fn main() {}", "rust", Some(DefaultThemes::MochaDark))?;
```
```

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

### Parse and read a recipe with Recipe::parse

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/recipe-core.md

Shows how to parse a recipe file and print basic fields: name, base image reference, and module count. Uses the `?` operator to propagate parse errors.

```rust
use blue_build_recipe::{Recipe, RecipeGetters};

fn main() -> miette::Result<()> {
    let recipe = Recipe::parse("recipes/recipe.yml")?;
    println!("name: {}", recipe.get_name());
    println!("base: {}", recipe.base_image_ref()?);
    println!("modules: {}", recipe.get_modules().len());
    Ok(())
}

```

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

### ManifestCreateOpts struct

Source: https://github.com/blue-build/cli/blob/main/_autodocs/api-reference/drivers-opts.md

Options for creating a manifest. The final_image field is required, while image_list defaults to an empty slice.

```rust
pub struct ManifestCreateOpts<'scope> {
    /// The final image name.
    pub final_image: &'scope Reference,
    /// The list of images to roll up under the manifest.
    #[builder(default)]
    pub image_list: &'scope [Reference],
}
```