An option changes one command’s behavior. Aède separates true shared options from reusable command-scoped families and specialized flags. Never assume that a familiar option applies everywhere: the command’s own table is the practical reference.
Shared presentation and data options#
| Option | Meaning |
|---|---|
--data FOLDER | Use this Aède data directory, not a music folder to scan. Applies wherever the operation reads/writes stored data. |
--no-color | Disable terminal ANSI colors. |
--help, -h | Show index or current command help and stop. |
--version, -v, -V | Print executable version and stop. |
Data precedence is --data, AEDE_HOME, $XDG_DATA_HOME/aede, ~/.local/share/aede, then .aede in the working folder if HOME is unset. A direct file inspection needs no catalog; playback still uses the data directory for catalog selections/history. Use one location consistently with the server.
How to type values#
aede albums --limit 10
aede albums --limit=10
aede track "So What" --artist "Miles Davis"
aede play "/path/to/audio.flac" --bass -2
aede note album "Kind of Blue" --file -
aede file -- ./-track.flac
Both --option value and --option=value work. Paths/numbers/keywords take one token. Name-valued options (--artist, --album, --with, --genre, --label, --comment, --role, --country, --text, --from, --tag, --query, --collection, --instrument) consume words until the next option: put the positional name first. Quote multiword paths and names to make boundaries explicit. -- ends option parsing for a path starting with a dash. A lone - is accepted as standard input for notes. --bass -2/--treble -2 specially accept a negative numeric value; --bass=-2 also works.
Short forms are separate options: -j means command-scoped --json, -o FILE means command-scoped --output FILE. -o=FILE is supported. Do not combine short letters (-jo); that is not a declared alias. Unknown/missing-valued options are validated even before help/version. Repeating the same option currently keeps the last value; write it once to avoid accidental replacement.
Valueless flags such as --yes, --json and --help refuse inline values, including =false, =true and an empty =. They are presence switches, not boolean-valued options. This validation happens before help/version, confirmation or any data change; omit --yes when confirmation should remain required.
Reusable families#
Pagination: --limit N, --offset N, --all only on the commands below. N is a whole number; limit must be positive, offset starts at zero, all and limit are incompatible. Ordinary paged lists generally default to 50; some reports choose smaller subsidiary lists. Export preserves the actual filtered/paged rows, so request all deliberately.
Output: choose one of CSV, JSON or M3U where supported. --output/-o writes a real export, not arbitrary human pages. --separator requires CSV; export --tracks requires CSV. CSV uses RFC-compatible quoting; tools that split blindly on commas can corrupt quoted titles. --separator tab avoids that for simple tab-delimited shell workflows. M3U contains file paths and does not copy sound.
Export destinations are checked before a command changes personal data. Active Aède stores and writer locks, existing audio files, symbolic links and non-regular targets are refused. An ordinary report is replaced atomically after its full content is written; missing report folders may be created. Human terminal output escapes control instructions in notes, paths and metadata. JSON/CSV exports preserve original values; treat CSV text as untrusted data when opening it in a spreadsheet.
Confirmation: --yes exists only for reset, history, fetch, backup and restore. It skips that command’s actual confirmation; it is not a universal “ignore errors” option. Without a terminal, a needed confirmation refuses unless deliberately accepted.
Work reuse: --full belongs to scan/check/spectrum/fetch/fingerprint with different meanings; analyze uses --force. Never infer behavior from the name alone.
Complete recognized-option matrix#
This inventory follows the current dispatcher and handlers. It lists accepted command scope, not a promise that every combination is valid. Specialized constraints are documented per command. Current known handler gaps: missing --source and merge --source are accepted but not applied; sources --source filters list/forget and selects template provenance, while summary/export currently include every source. --compress/--quality belong semantically to copy although the current dispatcher does not reject those recognized names on every unrelated command. Use only their documented copy scope.