Aqua CLI

curl -fsSL https://aquavoice.com/install-cli | sh

brew install aqua-voice/tap/aqua

irm https://aquavoice.com/install-cli.ps1 | iex

To get the latest version, run aqua update. If you installed with Homebrew, run brew upgrade aqua-voice/tap/aqua instead.

aqua auth login

This opens your browser. Over SSH, or with --no-browser, aqua prints a URL and a code instead. Open the URL in a browser on any device and enter the code.

To see who is signed in, run aqua auth status. To sign out, run aqua auth logout. To transcribe audio, you also need an API key: see Transcribe audio.

aqua dict add Siobhan Kubernetes "Hacker News"

Each argument is one entry. Words you already have are skipped, ignoring case. To see your words, run aqua dict list. To remove one, run aqua dict remove Kubernetes.

A single word needs no quotes. Put quotes around a phrase with spaces, or your shell splits it into separate entries. The quotes are for your shell: Aqua saves the text without them. Use single quotes when the text has $, !, or a backtick, because the shell changes those inside double quotes. The same rules apply to remove and to replacements.

aqua dict add Kubernetes        # one word: no quotes
aqua dict add "Hacker News"     # a phrase: one entry
aqua dict add Hacker News       # no quotes: two entries, Hacker and News
aqua dict add "Ben's Diner"     # an apostrophe: use double quotes
aqua dict add 'Ca$h App'        # $, !, or a backtick: use single quotes

To add a lot of words at once, see Import and export.

aqua replacements add "my email" "maya@northstar.studio"

If you already have a replacement for that phrase, this changes it. To see yours, run aqua replacements list. To remove one, run aqua replacements remove "my email".

aqua instructions edit

This opens your instructions in $VISUAL or $EDITOR. Save and close the editor to apply your changes. If they change on another device while you edit, aqua does not save over that change. It keeps your version in a file and tells you where.

To add one line without an editor:

aqua instructions append "Write ticket IDs like ENG-142 in uppercase."

aqua instructions get prints your instructions. aqua instructions set "Use British spelling." replaces all of them, and aqua instructions clear deletes them. It asks first; in a script, add --yes. set and append read stdin when you pass -, as in aqua instructions set - < instructions.md.

Every change goes to your Aqua account. It applies from your next dictation, on all your devices. In the desktop app, the change shows within a few seconds on the page that lists it. To open that page:

aqua app dictionary

The other pages include replacements and custom-instructions. Run aqua app --help for the full list.

If the desktop app is not installed, aqua app opens its download page. Over SSH, add --print to print the link instead.

aqua dict import words.txt

Import adds what is in the file and keeps what you already have. For replacements, use aqua replacements import. The file type comes from its extension:

.txt

Dictionary: one word or phrase per line. A line that is # or starts with # is a comment, so words like #general still work. Replacements: from, a tab, then to on each line.

.csv

Dictionary: words in the first column. Replacements: from,to on each row. A from,to header row is skipped.

.tsv

Like .csv, with tabs between columns.

.json

What export prints. A plain JSON list of words, or of {"from": …, "to": …} objects, also works.

To make your list match the file exactly, add --replace. This also removes entries that are not in the file, so it asks first. In a script, add --yes. To see the changes first, add --dry-run. It prints one line per change, such as + Siobhan or - Kubernetes, and changes nothing.

aqua dict import words.txt --replace --dry-run

To back up, export to JSON. Import reads it back.

aqua dict export > dictionary.json
aqua replacements export > replacements.json

For other formats, add --format txt or --format csv to either export.

Transcription needs an API key. Create one in the API dashboard, then paste it when asked:

aqua auth login --with-api-key

You can also set AQUA_API_KEY. Transcription uses the Aqua API and costs $0.39 per hour of audio, with a 10-second minimum. The first $1.00 is free.

Then transcribe a file. The transcript prints to the terminal, so redirect it to save it:

aqua transcribe memo.m4a > memo.txt

Files can be flac, m4a, mp3, mp4, mpeg, mpga, ogg, wav, or webm, up to 25 MB and under one hour each. You can pass many files, such as aqua transcribe *.mp4 --format srt --out subtitles/. Other options:

--format srt

Subtitles. The other formats are text (the default), json, verbose_json (with segment timestamps), and vtt.

--out transcripts/

Write each transcript to a file instead of the terminal: memo.m4a becomes transcripts/memo.txt.

--language de

Set the spoken language instead of detecting it.

--prompt "Siobhan, Kubernetes"

Names and terms to expect, so Aqua spells them right.

--jobs 5

Transcribe up to 5 files at once. The default is 3.

-

Read audio from stdin: curl -sL https://example.com/talk.mp3 | aqua transcribe -

In a terminal, output is for people. In a pipe, it is plain: one value per line, or tab-separated columns with no header. Tabs, line breaks, and backslashes in values print as \t, \n, and \\, so each row stays one line. Status messages go to stderr, so they never mix with data. -q hides them.

aqua dict list | wc -l
aqua replacements list | cut -f1

--json prints JSON. --jq filters it, and you do not need jq installed:

aqua dict list --json
aqua replacements list --jq '.replacements[].from'

transcribe --json is the one --json that prints a list: one entry per file, in order, for any number of files. A file that failed has an error with its exit code and message instead of text. If a --jq filter fails, the unfiltered list is printed and the exit code is non-zero. If no file could start (a bad file or no API key), stdout is empty and the exit code says why:

aqua transcribe *.m4a --json
# [{"file": "a.m4a", "text": "..."},
#  {"file": "b.m4a", "error": {"code": 1, "message": "..."}}]
aqua transcribe *.m4a --jq '.[].text'

In CI, set AQUA_API_KEY to an API key instead of signing in. To check the result of a command, use its exit code.

Install a skill that teaches your coding agent to use aqua. Then you can ask it things like "add the names in this doc to my Aqua dictionary."

aqua setup claude

For Codex, run aqua setup codex. After aqua update, run it again to get the latest skill.

aqua auth login | status | logout

Sign in, see who is signed in, or sign out. login --with-api-key asks for an API key, or reads it from stdin.

aqua dict list | add | remove | import | export

Manage your dictionary.

aqua replacements list | add | remove | import | export

Manage your replacements.

aqua instructions get | set | append | edit | clear

Manage your custom instructions.

aqua transcribe <file>… | -

Transcribe audio files, or audio from stdin.

aqua app [page]

Open the desktop app, on a page if you name one. If the app is not installed, open its download page.

aqua setup claude | codex

Install the aqua skill for a coding agent.

aqua update

Update aqua to the latest version.

aqua version

Print the aqua version.

aqua completion <shell>

Print a completion script for bash, zsh, fish, or powershell.

Run aqua <command> --help for its flags and examples.

0

Success

1

Error

2

Not found, such as a word that is not in your dictionary

3

Not signed in, the sign-in expired, or Aqua did not accept your API key or token. The error says which.

4

Usage error: a bad command, flag, argument, or input

5

Rate limit, or a billing problem. The error says what to do.

6

Network error: aqua could not reach the server

7

Transcription needs an API key. Signing in again does not help.

130

Interrupted with Ctrl-C (macOS and Linux)