CLI Reference

Top-level commands

bulker activate

Put crate commands on PATH. This is a shell function that modifies the current shell’s PATH.

bulker activate <crate> [-s] [--strict-env] [--echo] [--hide-prompt] [-f] [-n <name>] [-c <path>]

Flag	Description
<crate>	Registry path (namespace/name:tag), comma-separated list, or local file path
-s	Strict mode: only crate commands on PATH (no host commands)
--strict-env	Clean container environment: only pass envvars allowlist (config + manifest)
--echo	Print export commands instead of launching a shell
--hide-prompt	Do not modify the shell prompt
-f, --force	Re-fetch manifests from registry even if cached
-n, --name	Override crate identity for local manifests (e.g., myorg/mytool:1.0)
-c <path>	Config file path

Auto-fetches the manifest from the registry if not already cached. No separate install step needed.

bulker deactivate

Restore the original PATH, removing all crate commands.

bulker deactivate

bulker exec

Run a single command in a crate environment without modifying the current shell. Preferred for scripts and AI agents.

bulker exec <crate> [-s] [--strict-env] [-p] [-n <name>] [-c <path>] -- <command> [args...]

Flag	Description
<crate>	Registry path, comma-separated list, or local file path
-s	Strict mode
--strict-env	Clean container environment: only pass envvars allowlist
-p	Print the container command instead of running it
-n, --name	Override crate identity for local manifests (e.g., myorg/mytool:1.0)
-c <path>	Config file path

bulker init-shell

Print the shell function definition for activate/deactivate. Add to your shell RC file.

bulker init-shell bash|zsh

The install script runs this automatically. If you need to add it manually:

# Add to ~/.bashrc
eval "$(bulker init-shell bash)"

# Add to ~/.zshrc
eval "$(bulker init-shell zsh)"

bulker completions

Generate shell completion scripts.

bulker completions bash|zsh|fish

See Shell Completions for setup instructions.

crate subcommands

bulker crate install

Pre-cache a manifest from the registry, a URL, or a local file. Optional — activate auto-fetches.

bulker crate install <crate> [-b] [-n <name>] [--no-overwrite] [-c <path>]

Flag	Description
<crate>	Registry path or local file path
-b	Also pull/build all container images
-n, --name	Override crate identity for local manifests (e.g., myorg/mytool:1.0)
--no-overwrite	Don’t overwrite locally modified cached manifests

bulker crate list

List cached crates.

bulker crate list [--versions] [--simple]

Flag	Description
--versions	Show all installed tags
--simple	Space-separated output for scripting

bulker crate inspect

Show the commands available in a crate.

bulker crate inspect [<crate>]

If <crate> is omitted, inspects the currently active crate (from $BULKERCRATE).

bulker crate clean

Remove a cached crate.

bulker crate clean <crate> [--all]

Flag	Description
--all	Clear entire cache

bulker crate digest

Show a content-addressable digest for a cached crate. Useful for reproducibility verification.

bulker crate digest <crate> [--verbose] [--resolve]

Flag	Description
--verbose	Show per-command digest details
--resolve	Resolve image tags to digests (requires network)

bulker crate compare

Compare two cached crates, showing added, removed, and changed commands.

bulker crate compare <crate_a> <crate_b> [--json]

Flag	Description
--json	Output as JSON

config subcommands

bulker config init

Create or reset the config file with auto-detected defaults. Not required for normal use — bulker auto-generates a config on first use.

bulker config init [-c <path>] [-e docker|apptainer] [-f]

Flag	Description
-c <path>	Config file path (default: ~/.config/bulker/bulker_config.yaml)
-e <engine>	Container engine: docker or apptainer (auto-detected if omitted)
-f, --force	Overwrite existing config file

bulker config show

Display the config file, or the effective config (file merged with built-in defaults).

bulker config show [--effective] [-c <path>]

Flag	Description
--effective	Show the effective config (all defaults filled in), even if no config file exists

bulker config get

Get a specific config value.

bulker config get <key> [-c <path>]

bulker config set

Set a config value.

bulker config set <key>=<value> [-c <path>]

For list values, use commas: bulker config set volumes=$HOME,/data,/scratch

bulker config add

Append an entry to a list config field.

bulker config add <key>=<value> [-c <path>]

bulker config remove

Remove an entry from a list config field.

bulker config remove <key>=<value> [-c <path>]

mock subcommands

bulker mock record

Record real container outputs for mock replay. Runs the given command with recording shims that capture stdout, stderr, return codes, and new files for each crate command invocation.

bulker mock record <crate> <outputs.json> [-c <path>] -- <command> [args...]

Flag	Description
<crate>	Registry path, comma-separated list, or local file path
<outputs.json>	Path to write/append recorded outputs (created if absent)
-c <path>	Config file path
-- <command>	The pipeline command to run under recording

bulker mock run

Replay recorded outputs without containers. Creates Python shims for each crate command that return pre-recorded stdout/stderr/returncode and recreate files.

bulker mock run <crate> <outputs.json> [-s] [--echo] [-c <path>]

Flag	Description
<crate>	Registry path, comma-separated list, or local file path
<outputs.json>	Path to the recorded outputs file
-s	Strict mode: only mock commands on PATH
--echo	Print export commands instead of launching a shell
-c <path>	Config file path

Global flags

Flag	Description
-v, --verbose	Enable debug logging (RUST_LOG=debug)
-c <path>	Path to config file
--version	Show version
-h, --help	Show help

Environment variables

Variable	Description
BULKERCFG	Path to config file (overridden by -c flag)
BULKERCRATE	Currently active crate (set by activate)
BULKERPATH	Original PATH before activation (set by activate)
BULKERPROMPT	Shell prompt format for active crates
BULKERSHELLRC	Path to shell RC file
BULKER_ORIG_PATH	Saved original PATH for restore on deactivate
BULKER_SHIMDIR	Path to the ephemeral shimlink directory (used by deactivate for cleanup)
BULKER_STRICT_ENV	If set to 1, containers use a clean environment with only the envvars allowlist. Set by --strict-env flag.
BULKER_PRINT_COMMAND	If set, shimlinks print the container command instead of running it
BULKER_EXTRA_DOCKER_ARGS	Additional Docker flags applied to all containers
BULKER_EXTRA_ENVVARS	Additional env var names added to the --strict-env allowlist
BULKER_MOCK_OUTPUTS	Path to the outputs.json file for mock replay (set by mock run)
BULKER_MOCK_RECORD_FILE	Path to the outputs.json file being written during recording (set by mock record)