AudD CLI

audd is the command-line tool for AudD. It recognizes music in files, URLs, folders, long recordings, and from the microphone; monitors your streams; and manages your account. It prints tables on a terminal and JSON when its output is piped, so the same commands work in a shell, in scripts, and for AI agents.

Source and releases: github.com/AudDMusic/audd-cli

Install

Where	Command
Any system with Node.js	`npx @audd/cli recognize song.mp3` (no install) or `npm install -g @audd/cli`
Any system with Python	`uvx audd-cli recognize song.mp3` (no install), `pipx install audd-cli`, or `uv tool install audd-cli`
macOS	`brew install auddmusic/tap/audd`
macOS, Linux	`curl -fsSL https://github.com/AudDMusic/audd-cli/releases/latest/download/install.sh \| sh`
Windows	`scoop bucket add auddmusic https://github.com/AudDMusic/scoop-bucket` then `scoop install auddmusic/audd`
Docker	`docker run --rm -e AUDD_API_TOKEN -v "$PWD:/work" ghcr.io/auddmusic/audd-cli recognize song.mp3`
Go	`go install github.com/AudDMusic/audd-cli/cmd/audd@latest`

Release archives for every platform are on the releases page. audd update installs the latest release, or prints the command for the package manager you installed it with.

audd login                               # sign in; fetches your API token for you
export AUDD_API_TOKEN=your-api-token     # or set the token directly (CI, scripts)

Get your API token at dashboard.audd.io, or let audd login fetch it. On a desktop, audd login opens the browser; over SSH and in containers, it prints a page and a code to approve the sign-in on any device. Recognition needs only the token; account, usage, billing, and token rotate need audd login. audd auth status shows which token is in use.

Recognize music

audd recognize song.mp3
audd recognize https://audd.tech/example.mp3
audd recognize song.mp3 --return apple_music,spotify
audd recognize mix.mp3 --at 1:30          # a 12-second clip from 1:30 (needs ffmpeg)
audd listen                               # record from the microphone and identify

The standard endpoint analyzes up to the first 12 seconds of audio. Use --at to pick another moment, or --enterprise to scan a whole recording. --return adds metadata from apple_music, spotify, deezer, and musicbrainz. No match is not an error: the result is null and the exit code is 0, unless you pass --fail-on-no-match.

Whole recordings

audd recognize mix.mp3 --enterprise --limit 20 --dry-run
audd recognize mix.mp3 --enterprise --limit 20 --tracklist

--enterprise uses the enterprise endpoint and returns every match with its position in the file. It is billed per 12-second chunk, so it needs --limit N (chunks per file) or --limit none. --dry-run shows the full cost without sending anything. --tracklist merges consecutive matches into tracks with start and end times.

Folders and lists

audd recognize ./recordings --max-files 200 --dry-run
audd recognize ./recordings --max-files 200 --format csv > results.csv
ls *.mp3 | audd recognize - --max-files 50 --yes

A folder, a glob, several files, or a list on stdin is a batch. It needs --max-files N (or none), shows a plan with the estimated number of requests, and asks to confirm; without a terminal, pass --yes. Every batch is saved as a job after each file, so Ctrl-C or a dropped connection loses nothing finished:

audd jobs list
audd jobs resume <id>

Results are cached by file contents, so recognizing the same audio again is free. --max-requests N stops any command before it spends more than N requests.

Streams

audd streams add https://radio.example/stream.mp3 --id 1
audd streams list
audd now-playing                          # full-screen view with cover art
audd streams watch                        # results as they arrive
audd streams history --since 24h
audd streams report --by artist --since 30d
audd streams export --since 7d --format csv > plays.csv

The CLI wraps the streams API. The first time you use a streams command, audd starts a background recorder that receives every result as it happens (over longpoll) and saves it locally, so history, reports, and the now-playing view stay complete. Receiving results needs a callback URL on the account; when it is missing, the CLI offers to set https://audd.tech/empty/, or you can set your own with audd streams callback set <url>.

audd now-playing shows the latest song on each stream with its cover art and the songs played before it, like the AudD widget. By default AudD sends a stream's result when the song ends; streams added with --start report songs when they start. Track length and a progress bar need provider metadata on stream results: audd streams callback set <url> --return apple_music.

audd streams watch --forward-to http://localhost:8080/callback POSTs each result to your URL, shaped like an AudD callback, for testing a callback handler locally.

Account

audd account
audd usage
audd usage --check --min-remaining 1000     # exit 8 when fewer remain
audd billing plans
audd billing subscribe <plan>               # prints a payment link
audd token show                             # masked; --reveal prints it
audd token rotate

Payment commands never charge: they print a Stripe link that you open and approve in the browser.

Interactive explorer

audd browse

audd browse opens a full-screen explorer with everything you recognized, your batch jobs, your streams live, and this cycle's usage. Search, open a song's links, export a view to CSV or JSON, and resume jobs from there.

Scripts and agents

Piped output is JSON; every document has "schema_version": 1. Batches and streams watch print JSON lines with a "type" field.
--format table|json|jsonl|csv picks a format; --fields a,b keeps only those fields (result.artist for nested ones).
Errors are JSON on stderr with a code, a message, and usually a hint with the next command to run.
Exit codes: 0 success (for a single file, no match counts as success), 1 a batch with files that had no match, 2 invalid input, 3 sign-in or token, 4 quota or plan, 5 network or server, 6 a safety bound (a missing --limit or --max-files, or a confirmation that needs --yes), 7 a batch with failed files.
audd commands --json describes every command, flag, and output.
audd api <method> key=value... calls any API method directly.

For coding agents:

audd agent-setup                 # write a skill or rules file for your coding agent
claude mcp add audd -- audd mcp  # use audd as a local MCP server
audd docs api                    # these API docs as markdown

audd mcp runs a local MCP server over stdio with tools for recognition, enterprise scans, streams, now-playing, usage, and the docs, with the same token and limits as the CLI. For account tools over OAuth without installing anything, see the AudD MCP Server.

Settings and profiles

audd config list
audd config set max_requests 500
audd --profile work recognize song.mp3

Each profile has its own sign-in, token, and settings. The CLI has no telemetry and talks only to AudD services, cover art hosts, and GitHub for the release check.

The full reference is in the README and audd <command> --help.

Install​

Sign in​

Recognize music​

Whole recordings​

Folders and lists​

Streams​

Account​

Interactive explorer​

Scripts and agents​

Settings and profiles​

See also​