CLI

~5 min

Separate audio stems from your terminal with stemsplit

GitHub Releases GitHub sourcev1.0.0

Prerequisites

StemSplit account with API key
macOS, Linux, or Windows
Credit balance for processing

Install

macOS — HomebrewRecommended

Install via Homebrew

brew install StemSplit/tap/stemsplit

Linux & Windows — GitHub Releases

Download the pre-built binary for your platform from the GitHub Releases page, make it executable, and move it to your PATH.

Linux install (x86_64)

# Download the latest release
curl -LO https://github.com/StemSplit/stemsplit-cli/releases/latest/download/stemsplit-linux-x64

# Make executable and move to PATH
chmod +x stemsplit-linux-x64
sudo mv stemsplit-linux-x64 /usr/local/bin/stemsplit

stemsplit --version

Set Up Your API Key

The CLI stores your key in a local config file so you don't have to pass it every time.

Store API key

stemsplit config set-key sk_live_xxx

Alternatively, export the key as an environment variable for CI/CD pipelines:

Environment variable

export STEMSPLIT_API_KEY="sk_live_xxx"

Quick Start

Run stemsplit separate on any audio file. By default the CLI separates vocals and instrumental and saves them next to the input file.

Separate stems

stemsplit separate song.mp3

Output

✔ Uploading song.mp3…
✔ Job created (job_abc123)
✔ Processing… [████████████████] 100%
✔ Done in 42 s

Outputs saved to ./
  vocals.mp3        (4.2 MB)
  instrumental.mp3  (4.1 MB)

Options

Customize output type, quality, format, and destination directory.

Flag	Values	Default
--output-type	`VOCALS` `INSTRUMENTAL` `BOTH` `FOUR_STEMS` `SIX_STEMS`	BOTH
--quality	`FAST` `BALANCED` `BEST`	BALANCED
--format	`MP3` `WAV` `FLAC`	MP3
--output-dir	Path to directory for output files	. (cwd)

Six-stem separation in WAV quality

stemsplit separate song.mp3 \
  --output-type SIX_STEMS \
  --quality BEST \
  --format WAV \
  --output-dir ./stems

YouTube

Pass a YouTube URL instead of a local file.

YouTube stem separation

stemsplit youtube "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --output-type VOCALS \
  --output-dir ./youtube-stems

Batch Processing

Pass multiple files or use shell globs — the CLI processes them sequentially and saves each file's stems to the output directory.

Batch separate all MP3s in a folder

stemsplit separate *.mp3 --output-dir ./stems

Output

✔ Processing track01.mp3… done
✔ Processing track02.mp3… done
✔ Processing track03.mp3… done

3 files processed. Stems saved to ./stems/

CI/CD Usage

The CLI is fully non-interactive when STEMSPLIT_API_KEY is set via environment variable. Exit codes follow Unix conventions:

Exit code	Meaning
0	Success
1	Job failed or API error
2	Invalid arguments or missing API key

GitHub Actions example

# .github/workflows/stems.yml
- name: Install StemSplit CLI
  run: brew install StemSplit/tap/stemsplit

- name: Separate stems
  env:
    STEMSPLIT_API_KEY: ${{ secrets.STEMSPLIT_API_KEY }}
  run: |
    stemsplit separate audio/song.mp3 \
      --output-type BOTH \
      --output-dir stems/

Tips

• Run stemsplit --help or stemsplit separate --help for a full flag reference
• Output URLs expire after 1 hour; the CLI downloads files automatically so you don't need to worry about this
• Use --format WAV for lossless stems when feeding into a DAW
• The CLI respects HTTP proxy environment variables (HTTPS_PROXY)

Python SDK

Integrate StemSplit in Python apps

Full API Docs

Complete endpoint reference