---
title: "Agent notes: the AudD CLI"
description: "Gotcha notes for AI agents running the audd command-line tool: JSON output, required limits and --yes, sign-in without a browser, exit codes, and when to call the API from code instead."
slug: "/resources/agents/cli"
section: "agents"
keywords: [audd, cli, agent, json, exit codes, limit, max-files, login, device code]
---

# 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](https://docs.audd.io/cli.md), and `audd agent-setup`
writes a skill or rules file for your harness.

## 1. Run it without installing

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

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

```json
{"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](https://docs.audd.io/.md) or an [SDK](https://docs.audd.io/sdks.md)
directly. `audd commands --json` lists every command and flag if you need to
check what the CLI can do.