Exec — unbg Docs

unbg exec runs inference locally and prints a JSON object with per-file results.

Top-level output looks like:

results: list of per-input result objects (or per-input errors in non-strict bulk runs)
timingsMs: timing summary when --profile is set; otherwise null

Inputs#

The -i/--input value can be:

A file path (.png, .jpg, .jpeg)
A directory path (scans for supported images)
A regex pattern (matched against file names under --input-root)

Examples:

# Single file
unbg exec -i ./photo.jpg

# Directory (recursive by default)
unbg exec -i ./images

# Regex: match files under a root directory
unbg exec -i ".*_product\\.(png|jpe?g)$" --input-root ./images

Supported input extensions are currently: png, jpg, jpeg.

Write outputs where you expect#

By default (no output flags), exec writes a cutout PNG next to the input file:

<input_stem>_cutout.png

If you specify only -m/--output-mask, the CLI writes just the mask PNG(s) (no cutout) unless you also pass -o/--output-cutout.

When processing multiple inputs (directory or regex match):

prefer --output-dir <dir> to set a single destination folder
if you pass -o/-m, they are treated as directories in bulk mode

Examples:

# Default output next to the image
unbg exec -i ./photo.jpg

# Explicit cutout path (single input)
unbg exec -i ./photo.jpg -o ./out/cutout.png

# Write both cutout + mask into an output directory (bulk)
unbg exec -i ./images --output-dir ./out -m ./out

If --inference-only is set, no outputs are written.

Tune runtime behavior#

-M, --model <auto|fast|quality|rmbg-1.4|rmbg-2.0> (default: fast)
-v, --onnx-variant <fp16|fp32|quantized|q8|auto> (default: fp16)
-e, --execution-provider <auto|gpu|cpu> (default: gpu)
-g, --gpu-backend <auto|directml|cuda|coreml|metal> (default: auto)
-p, --max-inference-pixels <n> (default: 2000000): downscale policy for very large inputs
--profile: include timing breakdowns in JSON output
--repeat <n> (default: 1): run the same input multiple times (useful for benchmarking)
--strict: abort the whole run on the first input error
-r, --input-root <dir>: root directory for regex matching (default: current directory)
--recursive <bool> (default: true): recurse when scanning directories / regex matches; pass --recursive false to disable
-d, --model-dir <dir>: explicit model directory
-o, --output-cutout <path>
-m, --output-mask <path>
--output-dir <dir>: output directory for bulk runs
-a, --allow-rmbg20 <bool> (default: true): allow selecting rmbg-2.0 where policy permits
--inference-only: run inference without writing mask or cutout files
-b, --benchmark-provider <bool>: enable provider benchmarking (advanced)

Read result fields (per input)#

Successful entries include (names as printed by the CLI):

input: input file path
modelUsed: resolved model, rmbg-1.4 or rmbg-2.0
providerSelected: cpu / gpu (or provider name, depending on runtime)
backendSelected: GPU backend selection (e.g. directml, cuda, etc.)
fallbackUsed: whether the runtime fell back from the preferred backend/provider
width / height: image dimensions used for the run
outputMask: path to the written mask PNG (if requested)
outputCutout: path to the written cutout PNG (if written)
timingsMs: per-input timing object with --profile; otherwise null

Let exec auto-install required models#

If the required model assets are missing, exec installs them before running.

Notes:

The install step reads a Hugging Face token from HF_TOKEN when required.
rmbg-2.0 may require a token / gated access depending on the upstream model policy.

Configure telemetry (optional)#

The CLI supports optional telemetry sinks configured via environment variables (stdout/file/http). See the core-sdk README for the current list and names:

unbgio/core-sdk