CLI Getting Started

decibri-cli is a cross-platform command-line tool for audio capture, playback, and device enumeration. It's a single statically-linked binary with zero runtime dependencies, built on the same Rust audio backend as the decibri Node.js and browser packages. This guide gets you from zero to recording and playing back audio in under five minutes.

Install

Three ways to install. Pick whichever fits your workflow best.

npm (recommended)

Downloads the platform-specific binary from GitHub Releases, verifies its SHA256, and adds it to your PATH. No Node.js runtime is required after installation, because npm is used only as a delivery channel.

Cargo

Builds from source. Requires Rust stable. On Linux, you'll also need the ALSA development headers: sudo apt install libasound2-dev on Debian/Ubuntu, or sudo dnf install alsa-lib-devel on Fedora.

Direct download

Pre-built archives for every supported platform are available on the releases page, along with SHA256SUMS and SLSA provenance attestations for supply-chain verification.

Your first commands

Check the version

decibri version

Prints the CLI version, the decibri library version it was built against, the audio backend for your platform, the Rust target triple, and the Rust compiler version:

decibri-cli 0.1.0
decibri 3.0.0
Audio backend: WASAPI
Platform: x86_64-pc-windows-msvc
Rust: 1.82.0

For machine-readable output, add --json:

decibri version --json

{
  "decibri_cli": "0.1.0",
  "decibri": "3.0.0",
  "audio_backend": "WASAPI",
  "target": "x86_64-pc-windows-msvc",
  "rust_version": "1.82.0"
}

List audio devices

decibri devices

Prints a human-readable table of all input and output devices on the system. Use --input or --output to filter, and --json for machine-readable output.

decibri devices --input
decibri devices --output
decibri devices --input --json

Record a WAV file

decibri capture -o recording.wav -d 10

Records 10 seconds of audio from your default input device to recording.wav. The default format is 16-bit PCM at 16 kHz mono, which is the format expected by most speech recognition engines. Press Ctrl+C at any time to stop early; decibri-cli writes a valid (truncated) WAV file, never a corrupted one.

Play a WAV file

decibri play recording.wav

Plays the file through your default output device. Supports 16-bit PCM integer and 32-bit float WAV inputs. Other WAV formats (24-bit, 8-bit, non-PCM codecs) produce a clear error rather than garbled output. Ctrl+C stops playback cleanly with exit code 0.

Common workflows

Record from a specific microphone

decibri devices --input
decibri capture -o out.wav -d 10 --device "Blue Yeti"

--device accepts either a case-insensitive name substring or a numeric device index from the devices listing. Name substrings are usually the more stable choice across runs.

Higher-quality stereo recording

decibri capture -o song.wav -d 60 -r 44100 -c 2

CD-quality 44.1 kHz stereo, 60 seconds. The encoding remains 16-bit PCM WAV, since v0.1.0 does not output 24-bit or float formats.

Round-trip check

decibri capture -o test.wav -d 5 && decibri play test.wav

Useful for verifying that input and output devices both work end-to-end. A simple audio loopback test for CI or new machine setup.

CI-friendly recording

decibri capture -o /tmp/ci-test.wav -d 2 --quiet --json

--quiet suppresses progress bars and status messages. Combined with --json, this is the pattern for shell scripts and CI pipelines. Exit code 0 on success, with a JSON summary on stdout describing the output file.

Exit codes

All commands use the same stable exit code contract:

Platform support

Pre-built binaries ship for every supported platform via npm, crates.io, and GitHub Releases. There is no source-build fallback. If your platform is not in the list, decibri-cli will not work.

Next steps