# 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](https://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](https://github.com/AudDMusic/audd-cli/releases). `audd update`
installs the latest release, or prints the command for the package manager
you installed it with.

## Sign in

```sh
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](https://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

```sh
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

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

`--enterprise` uses the [enterprise endpoint](/enterprise) 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

```sh
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:

```sh
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

```sh
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](/streams). The first time you use a streams
command, `audd` starts a background recorder that receives every result as it
happens (over [longpoll](/streams#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](https://widget.audd.tech).
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

```sh
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

```sh
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:

```sh
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](/mcp).

## Settings and profiles

```sh
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](https://github.com/AudDMusic/audd-cli#readme) and
`audd <command> --help`.

## See also

- [API reference](/) — the recognition API the CLI calls
- [Official SDKs](/sdks) — call the API from your own code
- [AudD MCP Server](/mcp) — account tools for AI agents over OAuth