Flags
All flags go before the tool name. Flags after the tool name are passed to the tool untouched.
Tool execution
| Flag | Short | Description |
|---|---|---|
--env <ARG> | -e | Build the tool's environment and compose in other tools, comma-separated. At most one segment is @provider[:file] (the primary tool's own packages — provider is always explicit, no inference from a bare filename); every other segment is name[@version][:package], composing that tool into the container with at most one inline package each. A segment may also name a group (e.g. coreutils) instead of a single tool — expands to that group's whole member list, either your own boks.toml [groups] table or a built-in index group. See Package managers |
--exec-as <BIN> | Run this binary instead of the tool's own resolved command, inside the same image/version/environment — for binaries installed by a package rather than a registered tool (e.g. --exec-as black python@3.12 -- --check . runs black, installed via requirements.txt, inside the python@3.12 env). Takes a single executable, not a shell command line — no spaces allowed | |
--watch | Watch the -e file and rebuild the image on change (runs until Ctrl+C). Requires an explicit -e @provider:file; doesn't support composed-tool segments | |
--cap <LIST> | Capabilities to enable, comma-separated: net, rw, ro, nomount, rwimg, browser, clipboard, pid, gpu, nonet, nobrowser, noclipboard. ro enforces read-only working directory (overrides image metadata). nomount skips mounting the working directory at all — an even tighter default than ro, for tools with no legitimate use for it (e.g. ping, dig). ro, rw, and nomount are mutually exclusive. nonet, nobrowser, and noclipboard force network/browser-relay/clipboard-relay off even if the tool's own default (or a composed tool) would otherwise auto-grant it — each is mutually exclusive with its positive counterpart (net/nonet, browser/nobrowser, clipboard/noclipboard), and nonet also conflicts with --port (a published port is useless without network). Same vocabulary a project's own .boksrc uses in capabilities: [...] | |
--port <PORT> | -p | Publish a container port to the host (HOST:CONTAINER, or a bare port mapping to itself). Repeatable. Implies --cap net |
--privileged | Remove capability restrictions. Kept separate from --cap deliberately — it's the single most dangerous escalation | |
--platform <PLATFORM> | Override container platform (e.g. linux/amd64) | |
--runtime <RUNTIME> | Override container runtime (podman, docker) | |
--non-interactive | Disable TTY allocation (auto-set when CI is set) |
Relays and host access
Enabled via --cap, e.g. --cap browser,clipboard:
| Value | Description |
|---|---|
browser | Enable the FIFO browser relay — lets the tool open URLs on the host (e.g. aws sso login) |
clipboard | Enable the OSC 52 clipboard relay — lets the tool write to the host clipboard |
pid | Share the host PID namespace (required for htop, ps, top to see host processes) |
gpu | Enable GPU device passthrough (CDI) — for GPU-accelerated tools. Requires the host's NVIDIA/AMD CDI setup (e.g. nvidia-ctk cdi generate) already in place — boks does not configure it |
Scanning
| Flag | Short | Description |
|---|---|---|
--skip-scan | Skip the vulnerability scan for this invocation | |
--force-scan | Force a fresh scan even if a cached result is still valid |
Offline mode
| Flag | Short | Description |
|---|---|---|
--offline | Run fully offline: no image pulls or freshness refreshes, no scanner-image pulls, no grype DB update, no index fetch. Only already-cached local state is used; anything not already cached fails with a clear error instead of hanging on an unreachable registry. boks --update --offline is rejected outright. [global] offline = true sets this permanently. See Offline mode |
Verbosity
By default boks shows transient progress: a spinner appears while an image is pulled, scanned, or built, and is erased once the step completes — a successful run leaves nothing behind but the tool's own output. Errors and user-actionable warnings always print, at every level.
| Flag | Short | Description |
|---|---|---|
--verbose | -v | Keep the output: ✔ READY / ✔ BUILT milestones persist after completion, plus background info lines (WATCH, SECURITY, REFRESH) |
--quiet | -q | Basically no output: no spinner, no progress lines, no milestones — only errors and warnings |
In non-interactive mode (CI, or piped stdio) the spinner is replaced by a
plain progress line (pulling <image>...), which persists in the log.
Precedence (highest wins): --quiet > --verbose > [global] verbosity >
the normal default. See Configuration > verbosity for the config key.
Tool management
| Flag | Short | Description |
|---|---|---|
--install | -i | Install a shim for TOOL |
--list | -l | List installed shims |
--clean [TARGET] | Reclaim disk: scratch, images, cache, all, decisions (default scratch,images) | |
--status | Show what boks is storing on disk, by category | |
--dry-run | With --clean: print the plan and remove nothing | |
--yes | -y | Pre-answer the --clean confirmation |
--search <QUERY> | -s | Search the tool index |
--info <TOOL> | Show a tool synopsis from the index and image metadata | |
--update | Fetch and cache the global tool index from index.boks.sh/index.json |
A tool's man page is not a flag — boks man <tool> runs man, an ordinary composable tool, against <tool>'s own image. See Commands.
Kubernetes
| Flag | Short | Description |
|---|---|---|
--k8s | Run tool in a Kubernetes pod | |
--namespace <NS> | -n | Kubernetes namespace |
--node <NODE> | Run on a specific Kubernetes node |
Help
| Flag | Short | Description |
|---|---|---|
--completions <SHELL> | Print a shell completion script (bash, zsh, fish, elvish, powershell) | |
--help | -h | Print help |
See Commands for usage patterns and Exit Codes for how boks propagates tool exit codes.