Agent notes: the AudD CLI

Terse notes for an agent that has a shell and wants to use AudD through the audd command-line tool instead of writing HTTP calls. The full reference is at docs.audd.io/cli, and audd agent-setup writes a skill or rules file for your harness.

1. Run it without installing

npx @audd/cli recognize song.mp3
uvx audd-cli recognize song.mp3

Either works on any machine with Node.js or Python. Use the same runner for every command in a session.

2. Your output is JSON already

When stdout is not a terminal, every command prints JSON, with "schema_version": 1 in every document. Don’t pass --format table and scrape it. Batches, streams watch, and streams export print JSON lines, each with a "type" of result, progress, summary, error, or event. Use --fields to keep the output small:

audd recognize song.mp3 --fields result.artist,result.title,result.isrc

3. No match is a success

A file with no match returns "result": null and exit code 0. Check result, not the exit code. A batch exits 1 when any file had no match, and 7 when any file failed.

4. Spending commands need explicit limits, and --yes

• A folder, a glob, or a list on stdin is a batch: it needs --max-files N.
• --enterprise is billed per 12 seconds of audio: it needs --limit N.
• Without a terminal, anything that could spend more than one request needs --yes.

A missing limit or confirmation exits 6 before anything is sent. Run with --dry-run first and show the user the plan (plan.requests and plan.cost_usd) before you add --yes. Never pass --limit none or --max-files none unless the user asked for the whole thing.

5. Sign-in without a browser

Prefer a token the user gives you: AUDD_API_TOKEN=.... If the user wants you to sign them in, audd login without a terminal prints a login_pending JSON record with verification_uri_complete and user_code, then waits. Show both to the user and keep the command running until it exits. Account commands (usage, billing, token rotate) need this sign-in; recognition needs only the token.

6. Read the error’s hint

Errors are JSON on stderr:

{"schema_version":1,"error":{"code":"limit_required","message":"…","hint":"…","retryable":false}}

hint is usually the exact next command. retryable: true means waiting and retrying can help (network, rate limit); false means it won’t.

7. Exit codes

Code	Meaning
0	Success, including a single file with no match
1	Unexpected error, or a batch with files that had no match
2	Invalid arguments, or a missing tool such as ffmpeg
3	Missing or rejected token, or sign-in needed
4	Quota, plan, or feature not available on the account
5	Network or server error
6	Safety bound: missing --limit/--max-files, --yes needed, or --max-requests reached
7	Batch finished with some files failed

8. Interrupted batches resume

Every batch is a job saved after each file. If one stops, don’t start it again from scratch: audd jobs list, then audd jobs resume <id>. Rerunning the same batch without a terminal exits 6 with resume_available; pass --resume or --new.

9. When to write code instead

The CLI is for one-off work, scripts, and checks. For an application that recognizes audio as part of its own logic, call the API or an SDK directly. audd commands --json lists every command and flag if you need to check what the CLI can do.