---
title: "Identify music from the command line with the AudD CLI"
description: "Use the audd command-line tool to identify songs in files and URLs, tag a folder of audio into a CSV, build a tracklist from a mix, and watch your streams, with no code."
slug: "/resources/recipes/command-line-music-recognition"
section: "recipes"
keywords: [audd, cli, command line, terminal, identify song, batch recognition, csv, tracklist, now playing, shell script]
---

# Identify music from the command line with the AudD CLI

`audd` is AudD's command-line tool. It covers what most projects first need
from the API (identify a song, tag a folder, list the tracks in a mix, follow
a radio stream) without writing any code. This recipe walks through those
four jobs, then shows how to use the same commands in a shell script.

## Install and sign in

Pick whichever package manager you already have:

```bash
npx @audd/cli version                 # Node.js, no install
uvx audd-cli version                  # Python, no install
brew install auddmusic/tap/audd       # macOS
```

Scoop, Docker, `go install`, and a one-line install script are listed in the
[CLI docs](https://docs.audd.io/cli). Then sign in:

```bash
audd login
```

`audd login` opens the browser to approve the sign-in, or prints a code to
approve it from another device when you're on a server. It fetches your API
token for you. If you already have a token, set it instead:

```bash
export AUDD_API_TOKEN=your-api-token
```

Get your own token at [dashboard.audd.io](https://dashboard.audd.io).

## 1. Identify one song

```bash
audd recognize song.mp3
audd recognize https://audd.tech/example.mp3
```

On a terminal you get a card with the cover art, artist, title, album, label,
and a link to listen. Add `--return apple_music,spotify` for the streaming
services' IDs and metadata.

The standard endpoint analyzes up to the first 12 seconds of audio. If the
song you want starts later in the file, send a clip from that moment:

```bash
audd recognize recording.mp3 --at 2:15      # needs ffmpeg
```

`audd listen` records from the microphone and identifies what's playing near
you.

## 2. Tag a folder of audio files into a CSV

```bash
audd recognize ./archive --max-files 500 --dry-run
```

A folder is a batch, and a batch always needs `--max-files`, so a typo in a
path can't send ten thousand files. `--dry-run` prints how many files it found
and how many requests the run would use, without sending anything. When the
plan looks right:

```bash
audd recognize ./archive --max-files 500 --format csv > archive.csv
```

The CLI asks you to confirm, then writes one row per file, with a column per
field: `artist`, `title`, `album`, `release_date`, `label`, `isrc`, `upc`,
`song_link`, and more. The `status` column says `matched`, `no_match`, or
`failed`, so files without a match stay in the CSV and you can see which ones
to check by hand.

Every batch is saved as a job after each file. If the run stops (Ctrl-C, a
dropped connection, a closed laptop), nothing finished is lost:

```bash
audd jobs list
audd jobs resume <id>
```

Results are also cached by file contents, so running the same folder again
later doesn't spend requests on files you've already identified.

## 3. Turn a mix into a tracklist

A DJ set or a radio show recording holds many songs, so it goes to the
enterprise endpoint, which scans the whole file. Enterprise is billed per
12 seconds of audio scanned, so it needs a limit on how many chunks to scan:

```bash
audd recognize set.mp3 --enterprise --limit 20 --dry-run
audd recognize set.mp3 --enterprise --limit none --tracklist
```

The dry run shows the full cost of the file. `--tracklist` merges consecutive
matches into one entry per track with its start and end time in the mix.

Start with a small `--limit` on a new kind of recording to check the results
before you scan whole files.

## 4. Watch a radio stream

```bash
audd streams add https://radio.example/stream.mp3 --id 1
audd now-playing
```

`audd streams add` subscribes the stream to recognition. AudD then identifies
every song that plays on it. `audd now-playing` shows the latest song on each
stream with its cover art and what played before.

The first streams command starts a small background recorder that saves every
result locally, so you can report on a stream later:

```bash
audd streams history --since 24h
audd streams report --by artist --since 30d
audd streams export --since 7d --format csv > plays.csv
```

By default AudD sends a stream's result when the song ends, with how long it
played. Add the stream with `--start` to get each song when it starts
instead.

## Use it in a script

Piped into another program, every command prints JSON instead of a table, and
every document carries `"schema_version": 1`:

```bash
audd recognize song.mp3 | jq -r '.result | "\(.artist) — \(.title)"'
```

`--fields` keeps only what you need, and `--format csv` works for any command
that prints rows:

```bash
audd recognize ./inbox --max-files 100 --yes --fields artist,title,isrc --format csv
```

Without a terminal, nothing can be confirmed by hand, so a batch needs `--yes`.
The exit code tells a script what happened: 0 for success (for a single
file, no match counts as success), 1 when a batch finished with files that had
no match, 3 for a sign-in or token problem, 4 for quota, 5 for network, 6 when
a safety limit stopped the command, and 7 when some files in a batch failed. For example, a cron job that warns before your requests run out:

```bash
audd usage --check --min-remaining 1000 || echo "AudD requests are running low" | mail -s "AudD quota" you@example.com
```

`audd usage --check` exits 8 when fewer requests remain than you asked for.

## Where to go next

- [CLI docs](https://docs.audd.io/cli) for every command and flag
- [Standard vs. enterprise vs. streams](/resources/concepts/standard-vs-enterprise-vs-streams)
  to pick the right endpoint when you move from the CLI to code
- [Official SDKs](https://docs.audd.io/sdks) for the same API from Python,
  Node, Go, and eight more languages