remove-bg CLI

The CLI requires a remove.bg API key to process images. You can provide it in two ways:

1. Environment Variable (Recommended)

To avoid specifying the key in every command, export the REMOVE_BG_API_KEY variable in your shell profile (e.g., ~/.bashrc or ~/.zshrc):

export REMOVE_BG_API_KEY=xyz

2. Per-command Flag

Pass the key directly using the --api-key flag:

removebg --api-key xyz images/image1.jpg

The basic syntax for the CLI is:

removebg [options] <file>...

Processing a directory of images

Saving to the same directory (default)

To remove backgrounds from all PNG and JPG images in a directory and save the results in that same directory:

removebg images/*.{png,jpg}

Note: This will create new files with the suffix -removebg.png (e.g., dog-removebg.png).

Saving to a different directory

To save processed images into a specific folder, use the --output-directory flag:

mkdir processed
removebg --output-directory processed originals/*.{png,jpg}

You can install the removebg CLI using Homebrew or by downloading a pre-compiled binary.

Using Homebrew

brew install remove-bg/homebrew-tap/removebg

Manual Installation

1. Download the latest stable release (supporting Windows, Mac, and Linux) from the releases page.
2. Unzip the .zip or .tar.gz file.
3. Move the binary to a folder in your system PATH to use the removebg command globally.

The remove-bg CLI allows you to remove backgrounds from images via the command line. It supports processing individual files or entire directories. The tool can automatically inject configuration from environment variables and provides a progress bar for batch operations.

To use the CLI, provide the input files or paths as arguments. If you are processing a large number of images (more than 50 by default), the CLI will prompt you for confirmation before proceeding.

# Example: Processing a single file
remove-bg input.jpg

# Example: Processing multiple files or a directory
remove-bg ./images/

# Example: Specifying an output directory
remove-bg ./images/ --output-directory ./processed/

To avoid passing your API key as a command-line argument, you can set the REMOVE_BG_API_KEY environment variable. The CLI will automatically detect and use this value for authentication.

export REMOVE_BG_API_KEY='your_api_key_here'
removebg image.png

Produce a JPG with a grey background

removebg subject.jpg --format jpg --bg-color 7a7a7a --output-directory processed

Produce a large transparent PNG (up to 25 megapixels)

removebg large.jpg --size full --format png

Process an image with additional API options

removebg car.jpg --type car --extra-api-option add_shadow=true --extra-api-option semitransparency=true

The zip2png command is built into the CLI. It converts a .zip file (the result format from the remove.bg API) into a transparent .png file.

removebg zip2png --file /path/to/file.zip

These options are passed to the remove.bg API. For full details, refer to the API documentation.

• --size (default auto): Controls the output image size.
• --type: Specifies the type of image processing.
• --channels: Specifies the color channels.
• --bg-color: Sets a background color.
• --bg-image-file: Sets a background image file.
• --format (default png): The output file format.
• --extra-api-option: Forwards unlisted or new options to the API. Formatted as key=value. This can be used multiple times.
  • Example: --extra-api-option crop=true --extra-api-option add_shadow=true

Core Options

• --api-key or REMOVE_BG_API_KEY environment variable (required): Your remove.bg API key.
• --output-directory (optional): The directory where processed images will be saved.
• --reprocess-existing: Forces reprocessing of images that have already been processed (skipping is the default to save credits).
• --confirm-batch-over (default 50): Prompts for confirmation before processing batches larger than this number. Set to -1 to disable this safeguard.
• --skip-png-format-optimization: Uses png format instead of zip to save bandwidth, which limits output resolution to 10 megapixels.

Use ZipCanvas.fromBinary to take a ZIP archive containing color.jpg and alpha.png and composite them into a single image. This method also supports an optional origData parameter to include the original image as a hidden layer in the resulting output, and an opts.usePsd flag to export the result as a PSD file instead of a standard image.

// data is an ArrayBuffer of a ZIP file containing color.jpg and alpha.png
const opts = {
  usePsd: true, 
  bg_color: '#ffffff', // Optional background color for PSD
  resolutionInfo: { /* ... */ } // Optional resolution metadata
};

ZipCanvas.fromBinary(data, originalImageData, opts, (progress) => {
  console.log(`Stage: ${progress.stage}, Percent: ${progress.percent}%`);
}).then(compositeResult => {
  // compositeResult is a ZipCanvas instance or a blob object if usePsd is true
});

The version() function returns the current version of the remove-bg-cli package as defined in its package.json. If the version is not found, it returns 'dev'.

const { version } = require('./lib/client');
console.log(version());

The ZipCanvas class provides utilities for managing canvas-based image data, specifically for compositing color and alpha layers (often used when processing results from remove.bg). It supports exporting to different formats and can generate complex PSD files containing multiple layers (Original Image, Background, and the processed subject with a mask).

const { ZipCanvas } = require('remove-bg-tools');

// Example: Creating a ZipCanvas from an existing canvas
// Note: This class is designed for browser-like environments
const zipCanvas = new ZipCanvas(myCanvasElement);

// Export the canvas to a blob with specific options
zipCanvas.export({ mimeType: 'image/png', quality: 0.9 }).then(() => {
  zipCanvas.download('my-image.png');
});