Using the CLI

The CLI is FlacCompagnon without the graphical window: type a command in Terminal or PowerShell, give it a file or folder, and read the results there. It uses the same Rust analysis engine and the same JSON report schema as the desktop app. It reads your audio without changing it.

When only -a flac-md5 is selected without --json or --json-layout, the CLI decodes and verifies FLAC integrity only. It skips spectral analyses, transcoding detection and whole-file fingerprints. A failed MD5 comparison or decode returns a nonzero exit status. Other explicit selections also run only their requested measurements. JSON output keeps the complete analysis. Integrity-only checks use flac -t when the optional flac executable is on PATH, and the internal Rust verifier otherwise.

Install and check#

On the GitHub Releases page, choose a standalone archive named FlacCompagnon-CLI_<version>_<platform>.tar.gz or .zip. The graphical application files begin with FlacCompagnon-App, so the two downloads are distinguishable at a glance. The platforms are macOS Apple Silicon, Linux x86_64 and Windows x64.

Extract the archive. In its folder, run:

# macOS or Linux
./flaccompagnon --help
./flaccompagnon --version

# Windows PowerShell
.\flaccompagnon.exe --help
.\flaccompagnon.exe --version

The examples below assume the executable's folder has been added to your PATH. Otherwise replace flaccompagnon with ./flaccompagnon, .\flaccompagnon.exe, or its full path. On macOS, follow the release's first-launch instructions if the system blocks this unsigned build.

Analyze your first file#

flaccompagnon "Music/Album/01 - Track.flac"

Progress shows each file before analysis. Measurements are hidden by default; add --show-results to print them. An animated loader appears during file discovery and decoding in an interactive terminal. Quotation marks keep a path containing spaces together. An unavailable Rust value may appear as None; it is not a measured zero. Progress is sent to stderr; requested results go to stdout.

To scan an album, including its subfolders:

flaccompagnon "Music/Album"

You can mix several files and folders. To inspect only the named folder level:

flaccompagnon "Music/Album A" "Music/Album B" --no-recursive

Choose the analyses to run#

flaccompagnon "Music/Album" --analysis loudness
flaccompagnon "Music/Album" --analysis phase --analysis hf-stereo
flaccompagnon "Music/Album" -a clipping,clicks,dropouts

Without a JSON export, selection controls execution as well as terminal output. Only the requested measurements and their necessary dependencies run. Commas and repeated --analysis options combine any number of measurements. For example, -a flac-md5,loudness decodes once to verify audio integrity and measure loudness, without spectral or transcoding analysis. No selection means every analysis. --json and --json-layout require every analysis and cannot be combined with --analysis (-a). The CLI rejects this combination before scanning with exit code 2; it does not silently expand your selection.

Save and reopen a JSON report#

flaccompagnon "Music/Album" --json "Music/Album/FlacCompagnon.json"

--json requires a file path with a .json extension, not just a folder or a flag. The parent folder must already exist. Valid measurements in existing reports are reused when audio size and modification time agree. Add --force to reanalyze and replace the chosen report. A malformed destination requires --force. This command produces one report covering all selected audio files; use --json-layout album or --json-layout artist to split several albums into separate reports.

Symbolic links and special files are refused as destinations, even with --force. Reports are replaced atomically, so a failed write does not truncate the previous report. Imports accept regular files up to 64 MiB; unusable neighbouring JSON files are skipped during cache discovery.

The schema is the desktop app's complete, versioned flaccompagnon-report format. Drop the JSON onto the desktop results list to reopen the saved analysis without re-decoding the audio. A report is a snapshot: it does not update itself after audio is edited, and saved paths can become stale when files move. See file fingerprints for identity and relocation limits.

JSON exports always require all analyses. To display the complete measurements while saving them, use --show-results:

flaccompagnon "Music/Album" --show-results -j "Music/Album/FlacCompagnon.json"

Analysis reports with Aède#

Aède is a Rust music-library catalog. It organizes tracks and metadata and integrates the FlacCompagnon engine directly. It does not need to launch this executable.

With an Aède version that includes the integration, first catalog the files, then analyze them:

aede scan "Music"
aede analyze "Music" --json

Aède analyzes cataloged tracks and writes one <album>.json per album, using its catalog grouping (including multi-disc releases). Reports can be saved in album or artist folders, according to the chosen --json-layout album|artist option; --json defaults to album folders. An existing report can be imported with aede import "Music/Album/FlacCompagnon.json". Consult Aède's README for its version-specific options.

DSD and FFmpeg#

Ordinary PCM analysis does not require FFmpeg. DSD content analysis does; without a usable decoder, container information can still be read but content measurements are unavailable.

flaccompagnon "Music/DSD Album" --ffmpeg "/opt/homebrew/bin/ffmpeg"

Discovery uses the explicit --ffmpeg path first, then the FLACCOMPAGNON_FFMPEG environment variable, then PATH. The CLI does not generate spectrograms or edit tags.

Option reference#

flaccompagnon [OPTIONS] <FILE|FOLDER>...

Exit codes and automation#

An authenticity finding or a clipping event does not cause exit code 1. Inspect the JSON results if a script needs to react to those findings. A report may contain error entries and still be written before the process exits with code 1. Do not treat its existence alone as success.

Build from source and use the Rust library#

From the repository root, with Rust installed:

cargo build --release -p flaccompagnon-cli
./target/release/flaccompagnon --help

On Windows the executable is target\release\flaccompagnon.exe. This build does not require the Tauri desktop runtime. Other Rust software can depend on the flaccompagnon-core crate directly; its functions and report types are documented in Rustdoc. A Git dependency needs a pushed commit or tag; it does not need to wait for release binaries to finish building.

Reuse results and choose report placement#

flaccompagnon "Music/Artist" --json-layout album
flaccompagnon "Music/Artist" --json-layout artist
flaccompagnon "Music/Artist" --json-layout album --force
flaccompagnon "Music/Album" --show-results

album saves <album>.json inside each album folder; artist saves the same separate album reports in their parent folder. Audio files are grouped by directory; numbered CD, Disc and Disk subfolders share their parent album. This filesystem grouping does not use tags. --json-layout enables saving and cannot be combined with --json PATH or --analysis.

Even without saving, existing FlacCompagnon reports beside albums or in their parent folders can supply successful results. Files absent from reports, changed files and previous errors are analyzed. Reports are snapshots checked by path, size and modification time; use --force if those metadata stayed unchanged despite an audio edit or to recompute with a newer engine. --analysis also enables terminal results and filters their fields.

Aède accepts the same --force, --show-results and --json-layout album|artist options for aede analyze; --json retains its default album placement.