v0.1.20 · macOS 26 · MIT

Background,
gone.

The UNIX-style background remover for macOS. AI-driven via Apple's on-device Vision framework. No cloud, no API keys, no GUI side-effects. Pipe in, pipe out, exit zero.

brew install Arthur-Ficial/tap/bgbgone

Apple Silicon · macOS 26+ · or build from source

inout

Show, don't tell

One flag. Sixteen subjects.

Same CLI invocation across photography, painting, spacecraft imagery, woodblock prints and vintage product ads — every panel below is a real bgbgone in.jpg > out.png against a documented public-domain Wikimedia fixture.

Grid of 16 source → cutout pairs: NASA spaceflight imagery, paintings (Mona Lisa, Vermeer, Hokusai), 19th-century studio portraits (Einstein, Tesla, Wright Brothers, Edison) and vintage product ads (Singer, Underwood, Pierce-Arrow).

showcase-cutouts.png · 16 strict-PD subjects · zero per-image tuning · one bgbgone in.jpg

Tap a subject

Same subject, any background.

Tap a subject, then flip between the source, the transparent cutout, a solid white catalogue background, and a NASA Hubble nebula background. The CLI under each panel is the exact command that produced it.

Bruce McCandless EVA · NASAPD-USGov

bgbgone nasa-mccandless-eva.jpg > out.png

--feather

Soften the matte, not the subject.

Feather widens the alpha mask at the silhouette edge with a Gaussian blur — the foreground RGB pixels stay sharp. Drag the slider to preview a soft-edge composite. The radius is the exact pixel value the CLI uses.

Radius 0 px

bgbgone in.jpg --feather 0 -o out.png

The CSS blur here is a real-time preview only. The actual --feather blur runs against the alpha matte (Vision's foreground-instance mask) on-device, so the foreground texture stays sharp at the centre and the silhouette gradually fades.

How it works

Apple Vision in a UNIX pipe.

Every Mac since macOS 14 ships a foundation-model-class foreground extractor (VNGenerateForegroundInstanceMaskRequest). It is callable only from Swift. bgbgone is the thin, hard-tested CLI that wraps it.

~/photos

# single cutout to a transparent PNG
$ bgbgone photo.jpg > out.png

# on a brand background, JPEG, tight crop, soft edge
$ bgbgone selfie.jpg --bg color:#0066cc --crop --feather 2 \
    --to jpg --quality 95 -o avatar.jpg

# batch a folder, stream NDJSON for jq
$ ls *.heic | xargs -I{} bgbgone {} --ndjson --out-dir ./out/ \
    | jq -s 'group_by(.algo) | map({algo: .[0].algo, n: length})'

# pipe into auge for cleaner downstream classification
$ bgbgone in.jpg --bg color:black --to jpg -o /tmp/c.jpg \
    && auge --classify /tmp/c.jpg --top 3

100% on-device.

Vision runs locally on every Mac. There is no cloud, no API key, no telemetry. NetworkGuard.swift hard-blocks http / https / ws / wss inside the process and exits with code 3 if anything tries.

100% scriptable.

No GUI side-effects, ever. Pipe-friendly stdin and stdout, exits clean. Refuses to dump binary into a terminal, exactly like curl. --json and --ndjson for machine consumption.

No fallbacks, no half-features.

One code path per feature. If the primary path doesn't work, we fix the root cause or remove the feature. Unsupported names are rejected at parse with exit code 2 — never silently routed.

Matte controls

Feather, threshold, padding, shadow.

Every matte-shaping knob, on the same studio portrait — feather progression 0 → 16 px, then crop, padding, shadow and the raw alpha matte (--mask-only). The compositor blends with that matte to produce every other output.

Top row: --feather 0, 1, 4, 8, 16 progressively softening the edge of Einstein's studio portrait. Bottom row: original source, --crop, --crop --padding 10%, --bg color:white --shadow, --mask-only producing a black-and-white silhouette matte.

--feather · --crop · --padding · --shadow · --mask-only

--algo

Three algorithms, side by side.

Apple Vision exposes three public segmentation primitives that bgbgone surfaces directly. auto defaults to the foreground-instance mask path; person uses Vision's portrait segmenter; saliency uses the objectness heat-map.

--algo vn-mask, --algo person, --algo saliency on three subjects: Mars Curiosity rover selfie, the Wright Brothers in 1910, and the Mona Lisa.

--algo vn-mask · person · saliency · on three PD subjects

Two install paths

One brew tap. Two minutes.

Apple Silicon, macOS 26+. No Xcode required — bgbgone builds with Command Line Tools. Brew is the recommended path; source is one make install.

Homebrew

brew tap Arthur-Ficial/tap
brew install Arthur-Ficial/tap/bgbgone

bgbgone --version
bgbgone --check
bgbgone photo.jpg > cutout.png

Already installed? brew upgrade bgbgone.

From source

git clone https://github.com/Arthur-Ficial/bgbgone
cd bgbgone
make install

# bumps patch, builds release,
# installs to /usr/local/bin

Hack on it, regenerate the README assets with make readme-images, ship with make release.

Sibling tools

Part of the apfel ecosystem.

On-device CLI tools for the Apple frameworks Apple never wrapped. Each one is one binary, one purpose.

Tool	Capability	Apple framework
apfel	LLM (text generation)	FoundationModels
auge	Vision / OCR (see)	Vision
bgbgone (this)	Background removal (do)	Vision + Core Image
ohr	Speech-to-text	SpeechAnalyzer
kern	Embeddings	NLContextualEmbedding