Usage Guide#

A practical guide for common OS Image Composer workflows. For the complete command reference, see the CLI Specification.

Table of Contents#

Usage Guide

Binary Location#

The path to the os-image-composer binary depends on how you built or installed it:

Build method	Binary path
`go build ./cmd/os-image-composer`	`./os-image-composer`
`earthly +build`	`./build/os-image-composer`
Debian package	`os-image-composer` (installed to `/usr/local/bin/`)

The examples below use ./os-image-composer (the go build location). Substitute the path that matches your setup.

Commands Overview#

os-image-composer build         # Build an image from a template
os-image-composer validate      # Validate a template without building
os-image-composer inspect       # Inspect a raw image's structure
os-image-composer compare       # Compare two images
os-image-composer cache clean   # Manage cached artifacts
os-image-composer config        # Manage configuration (init, show)
os-image-composer version       # Display version info
os-image-composer --help        # Show all commands and options

For the full details on every command — including inspect, compare, and cache — see the CLI Specification.

Building an Image#

# go build — binary is in the repo root
sudo -E ./os-image-composer build image-templates/azl3-x86_64-edge-raw.yml

# earthly +build — binary is in ./build/
sudo -E ./build/os-image-composer build image-templates/azl3-x86_64-edge-raw.yml

# Debian package — binary is on PATH
sudo os-image-composer build /usr/share/os-image-composer/examples/azl3-x86_64-edge-raw.yml

# Override config settings with flags
sudo -E ./os-image-composer build --workers 16 --cache-dir /tmp/cache image-templates/azl3-x86_64-edge-raw.yml

Common flags: --workers, --cache-dir, --work-dir, --verbose, --dotfile, --config, --log-level. See the full build flag reference for descriptions and additional flags like --system-packages-only.

Build Output#

After the image finishes building, the output is placed under the configured work_dir. The full path follows this pattern:

<work_dir>/<os>-<dist>-<arch>/imagebuild/<system-config-name>/

The default work_dir depends on how you installed the tool:

Install method	Default `work_dir`	Example output path
Cloned repo	`./workspace` (relative to repo root)	`./workspace/azure-linux-azl3-x86_64/imagebuild/edge/`
Debian package	`/tmp/os-image-composer`	`/tmp/os-image-composer/azure-linux-azl3-x86_64/imagebuild/edge/`

You can override it with --work-dir or by setting work_dir in your configuration file.

Validating a Template#

Check a template for errors before starting a build:

./os-image-composer validate image-templates/azl3-x86_64-edge-raw.yml

Configuration#

The tool uses a layered configuration: config file values are overridden by command-line flags. A config file is auto-discovered from several standard locations (current directory, home directory, /etc/), or you can specify one explicitly with --config.

# Create a default configuration file
./os-image-composer config init

# Show the active configuration
./os-image-composer config show

# Use a specific configuration file
./os-image-composer --config /path/to/config.yaml build template.yml

Key settings:

Setting	Default (cloned repo)	Default (Debian pkg)
`workers`	8	8
`cache_dir`	`./cache`	`/var/cache/os-image-composer`
`work_dir`	`./workspace`	`/tmp/os-image-composer`

For the complete search order and all configuration fields, see Configuration Files in the CLI Specification.

Operations Requiring Sudo#

The build command requires sudo because it performs system-level operations: creating loop devices, mounting filesystems, setting up chroot environments, installing packages, and configuring bootloaders.

Always run builds with sudo -E to preserve your environment variables (such as $PATH and proxy settings).

Shell Completion#

# Auto-detect shell and install completion
./os-image-composer install-completion

# Or specify a shell: bash, zsh, fish, powershell
./os-image-composer install-completion --shell bash

After installing, reload your shell configuration (e.g., source ~/.bashrc). For per-shell activation steps and manual completion script generation, see the Install-Completion Command reference.

Template Examples#

Templates are YAML files that define the requirements for an image build. For the full template system documentation, see Creating and Reusing Image Templates.

The image-templates/ directory contains ready-to-use examples for all supported distributions and image types.

Minimal Edge Device#

image:
  name: minimal-edge
  version: "1.0.0"

target:
  os: azure-linux
  dist: azl3
  arch: x86_64
  imageType: raw

systemConfig:
  name: minimal
  description: Minimal edge device configuration
  packages:
    - openssh-server
    - ca-certificates
  kernel:
    version: "6.12"
    cmdline: "quiet"

Development Environment#

image:
  name: dev-environment
  version: "1.0.0"

target:
  os: azure-linux
  dist: azl3
  arch: x86_64
  imageType: raw

systemConfig:
  name: development
  description: Development environment with tools
  packages:
    - openssh-server
    - git
    - docker-ce
    - vim
    - curl
    - wget
    - python3
  kernel:
    version: "6.12"
    cmdline: "quiet splash"

Edge Microvisor Toolkit#

image:
  name: emt-edge-device
  version: "1.0.0"

target:
  os: edge-microvisor-toolkit
  dist: emt3
  arch: x86_64
  imageType: raw

systemConfig:
  name: edge
  description: Edge Microvisor Toolkit configuration
  packages:
    - cloud-init
    - rsyslog
  kernel:
    version: "6.12"
    cmdline: "console=ttyS0,115200 console=tty0 loglevel=7"