Welcome to Aria

Aria lets you type by speaking, hear text read aloud, and ask an assistant for help with a project. On a Mac or a Linux desktop, you can dictate into other apps with a hotkey.

Start here

Install Aria, then try Mac dictation, Linux dictation, or terminal dictation. Start with one short sentence so you can check the microphone, recognition, and output together.

Once that works, choose what you need next:

• Review or delete saved dictations.
• Read text aloud.
• Chat with an assistant.
• Correct project names.
• Create voice profiles.
• Transcribe audio playing on your Mac.

If setup or recording fails, start with Troubleshooting.

Your data

Dictation and speech generation run locally by default. You can move speech recognition to a personal server. Downloading models needs network access. Chat uses an external assistant, which may send your request and project content to cloud services.

History is on by default. Read Privacy before recording sensitive material; history controls explain what you can change.

For adding speech to your own Rust application, read Using Aria Libraries.

Install Aria

Download Aria from the latest release. Releases run on Apple silicon Macs with macOS 15 or later, and on x86_64 Linux.

Mac

With Homebrew, this installs Aria and links the aria command:

brew install --cask farhad-shabani/tap/aria

If Aria is already in Applications, add --force to replace it. Then open Aria to finish setup, as in step 3 below.

Without Homebrew:

1. Download Aria.dmg.
2. Open it and drag Aria to Applications.
3. Open Aria from Applications. It appears in the menu bar and opens its setup window. Continue uses the defaults; Customize… lets you choose engines and models.

When setup finishes, Aria asks for your password to add the aria command to the terminal. Skip it if you only use the menu bar app. Aria Setup in Settings → General asks again later.

If you can’t enter an administrator password, add this line to ~/.zshrc instead:

export PATH="/Applications/Aria.app/Contents/Helpers:$PATH"

Continue to Mac dictation.

Linux

Run:

curl -fsSL https://github.com/Farhad-Shabani/aria/releases/latest/download/install.sh | bash

The installer checks the download, installs the aria command in ~/.local/bin, and starts setup. If it reports that ~/.local/bin is not on your PATH, add it in your shell’s startup file.

Before setup, the installer offers a udev rule so the hotkey can read your keyboard. Installing it asks for your password. See Linux dictation for what it allows.

Aria needs a systemd user session for its background service and ALSA (libasound2) for audio. The service starts and stops with your graphical session through graphical-session.target. GNOME and KDE Plasma start that target. On a desktop that doesn’t, start the service from your session’s autostart:

systemctl --user import-environment DISPLAY WAYLAND_DISPLAY
systemctl --user start aria-daemon

For speech output, install a system voice:

sudo apt-get install espeak-ng

Continue to Linux dictation.

Setup

The Mac app and the Linux installer both start setup. To run it again:

aria setup

Keep the default Parakeet engine. Setup downloads the model for the engine you choose and shows its size first. Parakeet (MLX) is the exception: it needs its own Python and downloads its model on first use.

The system voice needs no model. You can leave optional features at their defaults.

You only need a Claude Code or Codex account if you want to use Chat or Prompts. Choose your assistant later in Settings → General → Assistant, or from the terminal.

Setup saves ~/.aria/settings.toml, downloads the models you select, and starts Aria’s background service. If a model download is interrupted, rerun setup to resume it.

To check the result:

aria doctor

Doctor reports settings, model-path, and service problems. It doesn’t record audio to test microphone permission.

Switch the speech model

To change only the speech model, name it. Setup keeps your other choices, downloads the model if it isn’t on disk, and switches without restarting the service:

aria setup --stt moonshine

The names are the ones stt.backend takes. For Parakeet (MLX), run aria setup instead. To recognize speech on your own server, see Server inference.

Free model space

A model stays on disk after you switch engines. On a Mac, delete one in Settings → General → Storage. In Terminal, see each model and remove one you no longer use:

aria models list
aria models remove parakeet

Aria keeps a model your settings still use. Setup downloads a removed model again if you choose its engine later.

Update or remove

On a Mac, Aria offers new releases itself. Choose Check for Updates… from its menu to check now, or set automatic checks and installs in Settings → About. With Homebrew, run brew upgrade --cask --greedy aria, because Aria updates itself and a plain brew upgrade skips it.

To remove Aria from a Mac, quit it and move it to the Trash, or run brew uninstall --cask aria. The aria command stays behind. Remove it with sudo rm /usr/local/bin/aria.

On Linux, rerun the install command to update. It keeps your setup answers and downloads nothing new; run aria setup to change them. To remove Aria:

curl -fsSL https://github.com/Farhad-Shabani/aria/releases/latest/download/install.sh | bash -s -- --uninstall

Removing Aria leaves ~/.aria, models included, in place. To delete saved dictations, use the history controls first.

Build from source

To build Aria yourself, follow Build from source in the README. just app builds the Mac app into clients/build/mac/Build/Products/Release/. A source build runs from its checkout, so keep that folder in place.

Mac dictation

Use Aria’s hotkey to type speech into an app. Complete installation and setup, then open Aria from Applications. It appears in the menu bar. To run setup again, open Aria Setup in Settings → General.

Permissions

Aria needs two permissions:

• Microphone to hear you. Allow access when macOS asks. If you previously denied it, turn on Aria in System Settings → Privacy & Security → Microphone.
• Accessibility to read the hotkey and type into other apps. When macOS asks, choose Open System Settings and turn on Aria. The switch is under System Settings → Privacy & Security → Device Control and Data Access (Accessibility before macOS 27). If Aria isn’t listed, click + and choose /Applications/Aria.app/Contents/Helpers/Aria.app. Use ⌘⇧G in the file picker to enter that path.

Try it

1. Open an empty document in a text editor and click where you want the text.
2. Tap right Option (⌥), say a short sentence, then tap it again to stop.
3. Keep that app and text field focused until processing finishes.

Transcribed words appear as segments become ready.

Tap or hold

Tap the key to start and tap again to stop. You can also hold it to record; recording starts half a second into the hold, and releasing the key stops it.

If you forget the second tap, Auto-stop ends the recording once you stop speaking. It waits 10 seconds by default. Change or turn it off under Settings → Dictation. Change the key to Fn under Settings → Shortcuts if you prefer. Fn then stops running the action set in Press fn key to in Keyboard settings, such as changing the input source.

Other keyboard or mouse input while you hold the key can cancel the recording.

Stop and send with Return

Press Return in the app you’re dictating into. Aria stops recording, types the rest, then presses Return for you.

If Aria can’t type the rest, or sees you moved to another field, it doesn’t press Return. The status pill then says return not sent.

Return in another app reaches that app, and recording goes on. With Output set to Copy to the clipboard, Return always reaches the app. Turn this off with Return sends under Settings → Dictation.

Cancel with Esc

Press Esc to cancel:

• A dictation you started with the Aria key or the wake word. Aria types nothing more, and text it already typed stays. The status pill says canceled, and Aria doesn’t save the dictation to history.
• An ask or a prompt while you speak it.
• A prompt while it runs. Once Aria starts typing the result, it types all of it.

Esc works in any app, and that app doesn’t receive it. Esc with Shift, Control, Option, or Command reaches the app. While Aria shows an ask’s reply, Esc goes to the Aria window, unless a prompt is running.

A dictation you start in the terminal keeps its own keys. See Stop by hand.

Ask or pick a prompt

Settings calls the key you tap the Aria key: right Option, or Fn if you chose it. Hold it, tap a second key, then let go:

• ⇧ Shift asks your assistant. Speak, then tap the Aria key to send. Aria opens on the chat and shows the reply there. Tap the Aria key again while Aria thinks to cancel.
• ⌘ Command opens Aria, where you pick a prompt.

Each is a setting under Settings → Shortcuts: keep the combo, record a shortcut of your own instead, or turn it off. Restore Defaults brings the combos back.

While Aria shows a chat, Ask follows up in it once its reply arrives. Once you close Aria, the next ask starts a new chat. While a prompt runs, pressing its combo again does nothing. The Aria key alone sends and cancels a question or prompt.

Any other key pressed with the Aria key cancels the press. Option shortcuts in other apps keep working. These presses need Accessibility access.

Choose a speech model

Settings → Dictation → Speech model lists the speech models your Mac can run. Models already on your Mac come first. The rest sit under Download, with their size.

Choosing a model that isn’t on your Mac downloads it. Your current model keeps working until the download finishes. Click Cancel to stop the download. Aria keeps the partial files, and choosing the model again resumes it.

Aria switches models between dictations, without a restart. If you’re dictating, the switch waits until you finish. The first dictation after a switch may wait a moment while the new model loads.

Whisper Tiny and Parakeet (MLX) type only after recording stops. While you use one of them, Deliver stays at After recording stops. Your choice returns when you switch back to a model that types while you speak.

While Recognize speech on your server is on in Settings → Recognition, your server chooses the model.

A model stays on your Mac after you switch away from it. To free its space, open Settings → General → Storage and click the trash button beside it. Models that a setting loads have no trash button. Choose a deleted model again to download it.

When your speech model can’t type while you speak, Transcription uses Parakeet. Parakeet still has a trash button then. If you delete it, Transcription reports it missing when a transcription starts.

Captions

Turn on Show captions in Settings → General to see what Aria hears in a panel while you record. Captions work with either delivery choice.

Settings → Dictation → Deliver decides when Aria types. With While speaking, Aria types finalized segments as you speak. With After recording stops, it types the completed text when you stop. If you switch away while Aria types segments, it keeps recording. The status pill shows the icon of the app it’s waiting for. Aria types what you said once you’re back in that field. If you stop while away, the status pill says where the words went: copied, saved to history, or not typed.

While Aria types segments, words it has heard but not typed yet show faintly at the cursor. Aria may still change them before it types them. Apps that do not report their cursor show none, and neither does Only type my voice. Turn them off with Show inline preview under Settings → General → On screen.

If output is set to copy, paste the text after recording. Copying always uses the completed text. Output choices are under Settings → Dictation.

Per-app settings

Settings → Apps gives an app its own output and delivery. Click +, pick the app, then choose its settings. Aria uses them when that app is in front as dictation starts. Switching apps mid-recording changes nothing. Other apps use Settings → Dictation. Flags such as aria dictate --mode copy still win.

Switch off the switch at the top of an app’s page, and Aria starts no dictation or chat and types or copies nothing while that app is in front, even from the phone. A dictation started in another app keeps recording. Its words wait for that app.

Dictate from iPhone and Apple Watch

Switch on Phone pairing under Settings → Phone. Aria restarts and shows a code for Aria for iPhone to scan. Switching it off keeps paired phones for next time.

Copy Code puts the code on the clipboard, marked hidden from clipboard managers and wiped when the code expires. Universal Clipboard may still carry it to your other devices meanwhile. Revoke All… unpairs every phone at once, and each phone scans a new code to pair again.

Keep Aria running

Dictation needs Aria’s background service. Opening the app starts it; choosing Quit Aria stops it until you open the app again. Keep Aria allowed under System Settings → General → Login Items → Allow in the Background.

You can enable Launch at login under Settings → General.

Once dictation works, you can correct project names or review its history.

Linux dictation

Use Aria’s hotkey to type speech into an app on GNOME, KDE Plasma, or an X11 desktop. Complete installation and setup first. The background service starts and stops with your desktop session.

Permissions

Aria needs two permissions:

• Keyboard access to read the hotkey. The installer offers a udev rule that gives the logged-in user access to keyboards, mice, and touchpads. Aria only reads them. Every program you run could read every key and inject input too. To add the rule later, run aria doctor and follow its steps.
• Keyboard control to paste into other apps on Wayland. Aria asks the desktop for permission and saves the grant when the desktop supports it. If you decline, Aria copies instead; restarting the service asks again.

X11 desktops need only keyboard access.

Try it

1. Open an empty document in a text editor and click where you want the text.
2. Tap right Alt, say a short sentence, then tap it again to stop.
3. Keep that app focused until the text appears.

On Wayland, Aria copies the text if keyboard permission is still pending when recording ends. Once permission is granted, later dictations can paste.

Tap or hold

Tap the key to start and tap again to stop. You can also hold it to record; recording starts half a second into the hold, and releasing the key stops it.

Other keyboard or mouse input while you hold the key can cancel the recording. Where right Alt is AltGr, typing characters with it still works. Only a press on its own starts Aria.

How text arrives

Aria puts the text on the clipboard and on the selection, then presses Shift+Insert to paste. The text stays on the clipboard afterwards.

Text arrives once you stop recording, not while you speak.

When keyboard control is unavailable, Aria copies the text for you to paste. This includes Wayland desktops without a remote desktop portal.

Aria can’t tell which app is in front on Linux. Text goes to whatever has focus when Aria pastes, and application_overrides, including excluded, have no effect.

Terminal dictation

Use aria dictate to record one utterance and copy the transcribed words. Complete setup and keep the background service running. On Linux, the service also keeps copied text available for pasting. It runs with your graphical desktop session so Aria can reach the clipboard.

Copy a sentence

aria dictate \
  --mode copy

Say a short sentence, then pause. By default, 1.5 seconds of silence ends the recording. After processing finishes, paste into an empty text field and check the words.

Copying replaces the clipboard.

Plain aria dictate uses your saved output setting. --mode copy chooses the clipboard for this recording without changing that setting.

Stop by hand

For a longer pause or a recording you want to end yourself, run:

aria dictate \
  --mode copy \
  --toggle

Speak, then press Esc when the terminal shows the stop prompt. Aria stops recording, finishes transcribing, and copies the text.

Without --toggle, silence ends the recording. With it, Auto-stop still ends the recording once you stop speaking, after 10 seconds by default. Change it under Settings → Dictation, or from the terminal:

aria settings show dictation.auto_stop_ms       # show the setting
aria settings set dictation.auto_stop_ms 20000  # stop after 20 seconds of silence
aria settings set dictation.auto_stop_ms 0      # stop on Esc or a second run

Recordings stop after ten minutes at most.

Insert into an app

On a Mac, hotkey dictation is the easiest way to speak into another app. A command launched in Terminal starts with Terminal focused. Insertion requires Accessibility access, and the intended app and field must stay focused.

--mode insert types the completed text. --stream types finalized segments while you speak. With Copy output or a speech model that can’t stream, Aria delivers the whole text once you stop instead. If you switch to another app or field, Aria keeps recording. It types what you said once you’re back in that field. Clicking or typing in that field stops the dictation, in apps that report their text cursor.

--mode insert-or-copy copies the text when insertion can’t begin. If you stop while away, it copies the words Aria hasn’t typed yet. --mode insert keeps those words only in history, when saving is on.

On Linux, hotkey dictation pastes into the focused app. --mode insert pastes the completed text. --stream waits too, since Aria pastes once recording stops.

To save the text to history without typing it, add --history-only.

On a Mac, Aria adds a space where the text needs one. Dictating “Hello.” and then “How are you” types “Hello. How are you”.

Clean up text

To tidy what you say, turn on Settings → Dictation → Clean up text, or run:

aria settings set dictation.cleanup.enabled on

Aria then drops “um”, “uh”, and repeated words, with either delivery setting.

With Deliver set to After recording stops, Aria also applies spoken corrections to the completed text. “Meet me at 3, actually 4” becomes “meet me at 4”. “Send it to Ali, scratch that, to Sara” becomes “Send it to Sara”. This handles only simple, unambiguous corrections within a clause, in English. More complex corrections stay as spoken.

Clean up text turns all of these on or off. To turn off one of them, set it in your settings file:

[dictation.cleanup]
enabled = true
fillers = true      # drops "um", "uh", and repeated words
backtrack = false   # keeps spoken corrections as you said them

Use a local model

A local language model can also fix punctuation, capitals, and spoken corrections. You run the model in a server on your own Mac, such as Ollama. Aria sends the text only to that server.

A cloud model sends your text off your Mac. Pick a model that runs on your Mac, such as qwen2.5:3b:

ollama pull qwen2.5:3b

Then add these lines to your settings file, and restart Aria:

[provider]
endpoint = "http://127.0.0.1:11434/v1/chat/completions"

[dictation.cleanup.llm]
model = "qwen2.5:3b"

The model runs only when both of these are true:

• Clean up text is on.
• Deliver is set to After recording stops.

To turn the model off and keep these lines, add enabled = false under [dictation.cleanup.llm].

A smaller model, such as qwen2.5:1.5b, misses most spoken corrections.

If the model doesn’t answer within 3 seconds, or adds words you didn’t say, Aria types the text without it. To check the setup, run aria doctor and look for the cleanup model line.

For names Aria regularly spells differently, try Project vocabulary. If recording fails, use Troubleshooting.

History

Aria saves completed dictations so you can review their text. These controls apply to both Mac and terminal dictation. History also lists each transcript that Transcription saves to the default folder, and each request you send in a chat, with its reply. The assistant keeps its own conversation records.

Saving

Saving is on by default. In the Mac app, turn it off under Settings → Privacy → Save history, or run aria settings set history.enabled off. This stops future saves and leaves existing entries until you delete them or they expire.

Aria deletes old history on its own, so personal text doesn’t pile up on your Mac. It deletes text after 30 days. A transcript’s entry keeps the first KiB of its text, and the transcript file holds the rest. When the entry expires, the transcript file stays.

By default, only recordings Aria couldn’t transcribe keep their original audio. Retained recordings last up to 24 hours, with a 128 MiB total limit. Cancelled recordings and recordings with no accepted speech are not saved in history.

Review

On a Mac, open Aria. Your dictations, transcripts, and chats show by day, each with its own icon. Type to search them. Press ⌘↩ to read one. Click Copy, or press ⌘C, to use the text elsewhere. For a chat, Copy takes the reply. A long transcript shows its first 1 MiB.

Press Return to type an entry’s text into the app you came from. With no app behind Aria, Return opens the entry instead. Text over 64 KiB is too long to type, so copy it.

To see one section alone, click its icon under the search field, or press ⌃Tab to step through them. You can also type its name and choose Dictations, Transcripts, or Chats. Search then covers only that section. Click All, or press Esc, to see everything again.

Continue a chat

Questions you send with the Ask shortcut stay together as a chat. Aria names a new chat after its first question. History lists each chat once, under its name. Search finds it by any question, reply, quoted text, or its name.

1. Select a chat and press ⌘↩. Aria shows its questions and replies, oldest first.
2. Type a follow-up in the field at the bottom, then press Return. Aria sends it to the same assistant, in the same folder.

Press ↑ or ↓ to select a question or reply, and ⇧↑ or ⇧↓ to select more. Press ⌘C to copy the selection. With nothing typed in the field, Return types the selection into the app you came from. Press ⌘. to stop a reply, and ⌘E to rename the chat.

Run a prompt on an entry

1. Select an entry, then press Tab or click Run Prompt.
2. Choose a prompt, or press its number. Aria shows the result.
3. Press Return to type the result into the app you came from, or press ⌘C to copy it.

With an entry selected, press ⌘ and a prompt’s number to run that prompt on it at once.

To run instructions of your own once, type them in place of a prompt’s name and choose Run “…”. Aria writes from them, as Write from them does, and names the result after their first line. To keep them as a prompt, press ⌘S on the result.

Press Esc on the result to cancel the run. If you close Aria instead, the run goes on. While Save history is on, Aria still saves its result.

With history on, Aria saves each result under its entry. An entry with results shows a chevron. Click it, or press →, to show the results under the entry. Press ← or Esc to hide them. Select a result and press Return to type it, or ⌘↩ to read it.

An entry keeps its 20 newest results, and all results share 8 MiB of text. Search doesn’t cover results. Deleting an entry, or clearing history, deletes its results too.

Ask about an entry or a result

You can ask your assistant about a dictation, a transcript, or a prompt result. Aria starts a new chat that quotes the text.

1. Select an entry or a result, then press ⌘↩.
2. On an entry’s page, press ↑ or ↓ to choose its text or one of its results.
3. Type a question in the field at the bottom, then press Return.

Aria shows the new chat with the quoted text above your question. It names the chat after the text’s first line and lists it under Chats. With nothing typed in the field, Return types the text into the app you came from.

If you go back while your assistant replies, the entry shows a spinner. Click it to open the chat. A chat’s own row shows the same spinner while a question you asked in Aria replies. Questions from aria ask or your iPhone don’t show it. Select either row and press ⌘. to stop the reply.

A transcript works only when Aria has its whole text. The text can be at most 128 KiB.

List entries in a terminal

From a terminal, run:

aria history list

The list shows each entry’s ID, section, status, recording availability (available, expired, or unavailable), and the first 512 bytes of its text. It lists each chat once, under its newest question, with the chat’s name in brackets. To list one section, add --section dictation, --section transcription, or --section chat. To list only entries that mention something, add --query TEXT. It matches the text, the entry’s name, the app’s name, and a chat’s reply, quoted text, and name, ignoring case. For scripts, add --json to print one JSON array. Each entry’s section is dictation, transcription, or chat. Each entry also carries created_at_ms, application, and the chat it belongs to.

To print one entry’s full text, or the prompt results saved under it, run:

aria history show 42
aria history results 42

To print a whole chat, rename it, or delete it, use its name from the list:

aria history chat show NAME
aria history chat rename NAME "NEW_NAME"
aria history chat delete NAME

Add --assistant for a chat with an assistant other than your usual one. chat show prints the chat’s quoted text first. With --json, it prints one object with the chat’s quote and its asks.

Dictate into history

To save a dictation without typing it anywhere, open Aria and choose New Dictation. Speak, then tap the Aria key to stop. Aria saves the text while Save history is on. From a terminal, run aria dictate --history-only.

Rename

From a terminal, give an entry a name by its ID:

aria history rename 42 "Weekly plan"

A name is one line of up to 256 bytes. Search matches it as well as the text. To remove the name, run the command without one.

Retry

If an entry still has its recording, open it in Aria and click Transcribe Again. From a terminal, use the entry’s ID. For example:

aria history retry 42

Retry replaces the entry’s text without keeping the previous version. It does not type or copy the result into another app. A failed retry leaves the previous text in place.

Retries use the same local or server setting as dictation. Enabled voice filtering runs locally before upload. The server must provide the requested engine. A failed retry leaves the saved text unchanged and never falls back to a local model.

Keep successful recordings

To make future successful dictations available for retry, enable Settings → Privacy → Keep audio for 24 hours, or run:

aria settings set history.keep_audio on

The same 24-hour and 128 MiB limits apply. Originals can include background speech and voices excluded from the text.

To stop keeping future successful recordings:

aria settings set history.keep_audio off

Existing recordings continue to expire.

Delete

In Aria, open an entry and click Delete… to remove it. To remove every entry and retained recording, type “clear” and choose Clear All History…. Clear includes entries outside the current search.

To delete a chat, select or open it, then press ⌘⌫. Aria deletes its questions, replies, and prompt results, but not the assistant’s own records. Aria can’t delete a chat while the assistant is replying.

From a terminal, delete one entry by its ID, or clear everything:

aria history delete 42
aria history clear

Answer y or yes to confirm. Any other answer cancels. In a script, add --yes. To clear one section, add --section as for aria history list. Clearing can’t be undone, and it leaves saving settings unchanged.

Deleting a transcript’s entry, or clearing history, also deletes its transcript file. Clearing history doesn’t remove clipboard copies, the assistant’s conversation records, or transcript files that history doesn’t list. Deletion isn’t secure erasure and can’t remove backups. Read Privacy for the other places text can go.

Read text aloud

Use aria say to play text through your chosen voice. Complete setup first. On Linux, keep the registered background service running.

Try it

aria say "Hello from Aria."

You should hear the sentence from your speakers. The command finishes when playback ends. A new utterance replaces the one playing.

To stop speech, run this in another terminal:

aria say \
  --stop

Speed and voice

For a faster voice on one request:

aria say \
  --rate 1.2 \
  "A little faster."

The rate is a multiplier between 0.25 and 4. Use --voice for a voice supported by the selected engine. To list installed system voices on macOS:

say \
  -v '?'

Use a name from that list. For example, if Samantha is available:

aria say \
  --voice Samantha \
  "Hello."

These options affect one utterance. To change the default rate, use Settings.

System voice

The system engine uses macOS’s installed voices, or /usr/bin/espeak-ng or /usr/bin/espeak on Linux. It needs no downloaded model. If a Linux system voice is unavailable, setup can offer Kokoro instead.

Kokoro

Kokoro generates speech locally from a model and voices file. Run aria setup and select Kokoro to download both. It uses English text processing.

If you already have the model and voices file, edit the existing tts section in ~/.aria/settings.toml, using their actual paths. Setup’s default paths are:

[tts]
backend = "kokoro"

[tts.kokoro]
model = "~/.aria/models/kokoro/kokoro.onnx"
voices = "~/.aria/models/kokoro/voices.bin"
voice = "af_heart"

Restart the service, then try the first sentence again. Voice names must exist in the downloaded voices file.

If you want the system voice when Kokoro can’t initialize, add fallback = "system" to the [tts] section. Fallback is off by default and applies when the engine or output can’t start.

If nothing plays, follow speech troubleshooting.

Chat with an assistant

Chat sends what you type or say to Claude Code, Codex, or a model on your Mac. The reply appears in your terminal, or in Aria on a Mac. To keep your requests on your Mac, see Use a local model.

Your request, and project files the assistant reads, may go to cloud services. Aria sends the assistant text, never audio. The assistant keeps its own conversation records. Read Privacy before you use private project content.

Before you start

1. Complete Aria setup.
2. Install Claude Code or Codex and sign in. Follow the Claude Code quickstart or Codex CLI setup, then check that claude or codex works in your terminal.
3. Choose that assistant in Settings → General → Assistant, or run aria settings set assistant.id claude-code or aria settings set assistant.id codex.

Keep Aria’s background service running. If you installed the assistant after Aria setup, follow the service restart steps so Aria can find its command.

Type a request

Open a terminal in a project you are comfortable sharing, then run:

aria ask \
  --project "$PWD" \
  "What does this project do?"

The reply appears in your terminal. --project gives the assistant a folder to work in. Aria runs it with read-only settings to limit file changes. The assistant can still read files and send their content to its service.

To continue the chat, ask again from the same folder with the same assistant:

aria ask \
  --project "$PWD" \
  "Where should I start reading?"

Speak a request

Once a typed request works, leave out the text:

aria ask \
  --project "$PWD"

Speak, then pause. Silence ends the recording. The reply appears in the terminal. If a spoken request fails, try a typed one. If that works, the problem is the recording.

Ask on a Mac

The Ask shortcut opens Aria on a chat with your assistant. To set it up, follow Ask or pick a prompt. To follow up later, see Continue a chat. To ask about a saved text, see Ask about an entry or a result. A chat started on a Mac is separate from the one aria ask continues in the same folder.

Cancel

To cancel, press Esc when the terminal shows its cancel prompt.

Start fresh

Each request continues the chat for that folder and assistant. Use --new to have the assistant start fresh:

aria ask \
  --project "$PWD" \
  --new \
  "Explain the tests."

Starting fresh does not delete the assistant’s earlier conversation records. Use --chat with a name to keep separate chats in one folder. A name can’t start with /, and each assistant’s chats have different names. A named chat runs in the folder where it started, even when you ask from another folder or with --project.

Use a different assistant or model

Add --assistant codex, --assistant claude-code, or --assistant local-model to use a different assistant for one request. Add --model "MODEL_ID" to choose a model for that request. Neither option changes your saved settings.

To see or change your usual assistant and model, follow Assistant settings.

Use a local model

The Local Provider assistant sends your request to a model server on your Mac, such as Ollama. It can’t read your project.

A cloud model sends your request off your Mac. Pick a model that runs on your Mac.

1. Download a model:

   ollama pull qwen2.5:3b
   

2. Add these lines to your settings file:

   [provider]
   endpoint = "http://127.0.0.1:11434/v1/chat/completions"
   
   [assistant.models]
   local-model = "qwen2.5:3b"
   

3. Follow the service restart steps.

4. Choose Local Provider in Settings → General → Assistant, or run aria settings set assistant.id local-model.

Send a request as in Type a request. The reply should appear in your terminal.

The local model remembers the chat only while history is on.

If a chat can’t start its assistant, check Troubleshooting. For names in spoken requests, Project vocabulary explains how to prepare the folder’s spellings.

Prompts (Mac)

A prompt turns what you say into finished text. You speak, and Aria types the result where you were. For example:

• Polish a rambling thought into a clean sentence.
• Turn “tell Sam I’m running late” into a friendly message.
• Translate what you said into French.

Each prompt is a Markdown file of instructions you write.

What you say and the prompt file go to Claude Code or Codex, which may send them to cloud services. Aria transcribes your speech before sending the text. Read Privacy before using a prompt.

Before you start

Set up Claude Code or Codex by following Chat with an assistant. Prompts use the same assistant and model as Chat. You can change both in Assistant settings.

Keep Aria.app running while you use prompt shortcuts.

Add a prompt

1. Open Settings → Prompts.
2. Click + and choose a Markdown file. The prompt takes the file’s name.
3. On the prompt’s page, set Your words:
   • Rewrite them keeps your words and meaning. It cleans them up or changes their style.
   • Write from them writes something new, such as a reply, a translation, or a summary.
4. Optional: click Record and press a shortcut, such as ⌃⌥P.

A shortcut needs Control, Option, or Shift. ⌘ alone isn’t enough, because ⌘ shortcuts belong to the app in front. To clear a shortcut, click ⓧ beside it.

A prompt without a shortcut still runs from Aria’s list.

A prompt file can be a few plain lines. For example, a polish.md set to Rewrite them:

Turn this into clean written text. Remove filler words and fix grammar.
Keep my meaning, names, and numbers.

Write a prompt in Aria

1. Open Aria, type “new prompt”, and choose New Prompt….
2. Enter a Name and choose Your words.
3. Type the instructions under Instructions.
4. Press ⌘↩ to save.

Aria saves the instructions in a new file in ~/.aria/prompts, named after the prompt. It never replaces a file that’s already there. To use a file you already have, click Choose…. Aria reads that file where it is.

Press Esc to leave. If you changed anything, Aria asks before discarding it. Aria keeps up to 16 prompts.

Use a prompt

1. Click into the app where you want the text.
2. Press the prompt’s shortcut and speak.
3. Tap the Aria key (right Option, or Fn if you chose it) to stop. Aria transcribes your speech, runs the prompt, and types the result.

To cancel while Aria works, tap the Aria key again or press Esc. Pressing the shortcut again does nothing until the run ends.

Aria types only into the app you were in when you started. Nothing is typed in these cases:

• You switched apps before stopping. Aria sends nothing to the assistant.
• You switched apps while the assistant worked. Aria drops the result.
• You said nothing. Aria sends nothing to the assistant.
• Aria is switched off for the app in Settings → Apps.

Some apps don’t accept typed text. Then the result goes to the clipboard, and the status overlay says copied.

In a terminal, take care. Each line break in the result types as Return, so a terminal runs each line as a command.

Pick a prompt in Aria

1. Hold the Aria key, tap ⌘, then let go. Aria opens over the app you’re in.
2. Press a prompt’s number to start it, then speak. Or type to find a prompt and press Return.
3. Tap the Aria key to stop. Tap it once more to cancel.

The first nine prompts that are on get a number. While Save history is on, Aria lists your history until you type. The numbers work either way. To use a shortcut of your own, or to turn it off, change Open Aria in Settings → Shortcuts. Opening Aria.app also opens Aria.

Esc clears what you typed, then closes Aria. Clicking elsewhere closes it too. The app you were in stays in front, so the result types there.

Change or remove a prompt

• Edit it in Aria: select the prompt in Aria and press ⌘E. Change it, then press ⌘↩ to save.
• Edit its file: change the Markdown file in any editor. Aria reads the file on each run, so the next run uses your edit.
• Turn it off: use the switch on its page. Its shortcut stops working, and Aria’s list hides it.
• Remove it: Control-click its row and choose Remove Prompt. Aria forgets the prompt but leaves the file alone.

Manage prompts from a terminal

List your prompts with their IDs:

aria prompt list

Each line shows the prompt’s ID, name, kind, whether it’s on, its shortcut, and its file. Add --json for one JSON array. Other aria prompt commands take a prompt’s ID or its name, ignoring case.

To add a prompt with its instructions:

aria prompt add \
  --name Polish \
  --instructions "Turn this into clean written text."

Aria prints the new prompt’s ID. You should see the prompt in aria prompt list and in Aria. As in Aria, the instructions go in a new file in ~/.aria/prompts. To use a file you already have, pass --file FILE instead. Without --name, the prompt takes the file’s name. With neither --instructions nor --file, Aria reads the instructions you pipe in. Add --kind compose for Write from them.

Other changes:

• Change it: aria prompt edit Polish --kind compose. It also takes --name, --file, and --instructions. The prompt keeps its shortcut and whether it’s on.
• Print its instructions: aria prompt show Polish.
• Turn it off: aria settings set prompts.ID.enabled off, with the ID from aria prompt list.
• Remove it: aria prompt remove Polish. Its file stays where it is.

Run a prompt from a terminal

Keep Aria’s background service running, then run:

aria prompt run Polish --text "so um I think we ship on friday"

Aria prints the reply. Without --text, Aria reads the text you pipe in. To run on a history entry, pass --entry ID instead. While Save history is on, Aria saves the reply under that entry. To run instructions of your own once, pass --instructions in place of the prompt’s name. Press Esc or Ctrl-C to cancel.

To type or copy the reply as a dictation does, add --mode insert-or-copy.

What a prompt can’t do

The prompt file supplies the instructions. Aria asks the assistant to treat your spoken words as the text to rewrite or build on.

Aria turns off the assistant’s tools for Prompts, so a prompt can’t read files, search the web, or run commands. Use Chat for help with a project.

When it fails

If a prompt fails, the status overlay shows an error and Aria types nothing. Common causes:

• The prompt file moved. Its row in Settings shows File not found. Choose the file again.
• The prompt file is empty, larger than 16 KB, or not text.
• The assistant isn’t installed or signed in. Check it with a typed request.

Dictation history doesn’t keep failed runs, so say it again.

Project vocabulary

Aria can correct names from a folder you choose. For example, “aria dash stt” can become aria-stt. This is optional and off by default.

Choose a folder

Aria reads file and folder names in that folder, never file contents. It skips hidden files and folders, and anything a .gitignore inside the folder excludes. It keeps a name only when it contains ., - or _ and is short to say. So Aria keeps Cargo.toml and vex16.rs, and skips README and icon-1024-dark.png. It stores the names it keeps, and their paths, in ~/.aria/vocabulary on your computer.

Complete setup and keep the background service running. Then choose the folder in the Mac app or in a terminal.

On a Mac:

1. Open Settings → Recognition.
2. Turn on Use project vocabulary.
3. Next to Folder, click Choose… and choose the folder.

In a terminal in that folder, run:

aria settings set dictation.vocabulary.enabled on
aria settings set dictation.vocabulary.dir "$PWD"
aria vocabulary status

You should see a line that starts with Ready, such as Ready: 784 of 784 names. For other results, see Read the status. Then dictate a name from the folder and check its spelling. For example, “cargo dot toml” types Cargo.toml.

If two names sound the same, such as aria-stt and aria_stt, Aria corrects neither.

Refresh the names

After you add or rename files, refresh the names:

aria vocabulary refresh
aria vocabulary status

Refresh runs in the background. Aria doesn’t watch the folder for changes.

Which folder applies

aria dictate uses the directory you run it from. Dictation with the Aria key uses the folder in dictation.vocabulary.dir. A folder includes the folders inside it. Aria doesn’t search upward for a project root.

For a spoken request, aria ask --project "$PWD" looks up names in that folder. It also gives the assistant that folder to work in. The assistant may send project content to cloud services. Read Chat with an assistant first.

Transcription doesn’t use project vocabulary. Live dictation types what you say in parts and corrects each part on its own. A name split across two parts may stay unchanged.

Read the status

aria vocabulary status prints how many names Aria uses, out of the names it found.

Turn off or forget

To stop corrections but keep the stored names, run aria settings set dictation.vocabulary.enabled off. To skip corrections for one dictation, run aria dictate --no-project.

To remove the names stored for a folder:

aria vocabulary forget "$PWD"

This also removes names stored for folders inside it and for folders that contain it. A later refresh stores them again, so turn off project vocabulary first if you don’t want that. Removing names isn’t secure erasure. For how Aria stores other content, read Privacy.

Wake word

Wake-word monitoring starts dictation when a local model detects its trained phrase. The recording stops on silence and delivers the completed text using your output setting. It doesn’t send anything to an assistant.

This keeps microphone monitoring active while the daemon runs. Wake-triggered dictation follows the same history setting as other dictation. Turning wake monitoring off does not close a microphone stream already used by the daemon; stop the daemon to stop its capture.

Setup

First make ordinary dictation work. You need a persistent daemon using microphone capture and a compatible wake-word model. Aria ships no wake-word model. Place an openWakeWord classifier in ~/.aria/models/wakeword as aria.onnx, beside melspectrogram.onnx and embedding_model.onnx.

Turn on monitoring in ~/.aria/settings.toml:

[wake]
enabled = true
backend = "openwakeword"
model = "~/.aria/models/wakeword/aria.onnx"
threshold = 0.5

Restart the registered service and check monitoring:

aria service stop
aria service start
aria wake status

Status must report listening before you try the phrase. On macOS, leave an editable field focused and ensure Accessibility access is granted for insertion. On Linux, Aria pastes into the focused app.

Speak the phrase trained into your classifier, then the sentence you want to dictate, and pause. The resulting text should arrive after recording stops. The model defines the phrase; changing the filename does not change what it recognizes. If you received a custom model, obtain its exact phrase from its builder.

Troubleshooting and stopping

aria wake status distinguishes listening, degraded, disabled, and stopped; only listening returns success. If it is degraded, inspect aria wake log and use aria doctor to check the model files. If it is disabled, check the settings and restart after changing it.

The threshold must be greater than zero and at most one. A higher value requires a stronger match and can reduce accidental triggers; it may also miss intended ones. Adjust it only after checking the model and microphone.

To disable wake triggers, set wake.enabled: false and restart the service. Ordinary dictation remains available, including after wake inference fails. To stop the daemon itself, use aria service stop.

Models

Supported backends are openwakeword and livekit. wake.model names one classifier file. Its directory must also contain melspectrogram.onnx and embedding_model.onnx.

The livekit backend needs its own classifier and an explicit wake.model path. livekit-wakeword’s hey_livekit.onnx model recognizes “hey livekit”. A classifier must match its selected backend.

Foreground operation

For troubleshooting, you can run the daemon in the terminal with monitoring forced on. This is an alternative to the registered service:

aria service stop
aria wake run

Stop the foreground process with Ctrl-C before running aria service start to restore the registered service.

Voice profiles (Mac)

This chapter is for Mac users. Enabling dictation filtering needs the Mac app, and Transcription, which uses speaker labels, runs only on a Mac.

A voice profile gives Aria a name for a speaker. An owner profile can also help it select your speech during dictation. A guest supplies labels for transcripts.

This is a recognition aid, not authentication. Filtering can allow other voices through when it cannot make a confident match.

Enroll

Complete setup, accept the speaker-model download, and keep the background service running. Allow microphone access when asked.

In the Mac app, open Settings → Recognition and click Set Up… under Voice. Enter your name, click Start, and read each sentence aloud. Pause after each one; the pause tells Aria the sentence is done. A voice added while there is no owner becomes the owner. Other voices are guests; add one with Add Voice….

In the terminal, to create an owner profile named alex:

aria speaker enroll alex \
  --role owner

Follow the prompts and provide clear recordings from one speaker. Enrollment asks for five utterances by default and checks that they agree before saving. After it succeeds, run:

aria speaker list

It shows each profile’s name and role.

Use your profile

Enrollment does not turn filtering on. In the Mac app, enable Settings → Recognition → Only type my voice. It is off by default. The CLI cannot change it, but CLI dictation follows it.

Aria rejects speech judged to be another voice. When there is too little usable audio to identify the speaker, it keeps the words without claiming an owner match. Without an enrolled owner, dictation fails instead of typing every voice.

Filtering is not a privacy guard. Short replies from other people can pass, and recognition can still miss words. Recordings kept for retry still hold every voice.

See who is speaking

While you dictate, the waves in the status pill show whether Aria is typing the voice it hears. They brighten for a voice it types and fade for one it excludes. Until Aria matches a voice, including short speech it keeps without an identity match, the waves stay at their usual red. A lost connection returns them to red until fresh voice information arrives.

Other speakers

To add a guest:

aria speaker enroll partner \
  --role guest

To make a guest the owner, choose Make Owner from its menu in Settings → Recognition, or run:

aria speaker owner partner

The previous owner becomes a guest.

Transcription names a voice with a profile once it is sure who is speaking. Other voices get numbers, such as Speaker 1. Labels can change as more audio arrives, so the saved transcript may differ from what the terminal printed first.

Replace or remove

In the Mac app, each voice in Settings → Recognition has a menu with Set Up Again… and Remove….

In the terminal, to replace alex with new recordings:

aria speaker enroll alex \
  --replace

A replaced profile keeps its role.

To remove a profile, use its name from the list:

aria speaker remove partner

Profiles are stored locally and contain a numeric representation of the voice. If enrollment fails, check the speaker-model path with aria doctor and use Troubleshooting.

Transcribe system audio (Mac)

Transcription saves a transcript of audio playing on your Mac, such as a meeting or video. It records what your Mac plays, not your microphone, and writes to a file.

Transcription needs System Audio Recording permission. First set up Mac dictation or terminal dictation, depending on how you installed Aria.

Record

You need two terminals: one shows the transcript, the other stops it.

1. Start the audio you want to transcribe, then run:

   aria transcribe start --follow
   

2. Allow System Audio Recording if macOS asks. The terminal prints transcribing -> and the file’s path. You should see text appear as the audio plays.

3. When you’re done, stop it in a second terminal:

   aria transcribe stop
   aria transcribe status
   

4. Check that status says not transcribing, then open the file.

Ctrl-C stops the display, not the recording. Always end with aria transcribe stop. To show live text again, run aria transcribe follow.

To start from the app, open Aria and choose Transcribe System Audio. Choose Live Transcript to see the text. While a transcription runs, the Aria menu shows Transcribing your Mac’s audio. Click the stop button beside it to end it.

Transcript files

By default, Aria saves files under ~/.aria/transcripts. To choose another path:

aria transcribe start \
  --output "$PWD/meeting.txt"

If the file exists, Transcription appends to it. Don’t run this while another transcription is running.

With history on, a transcript saved under the default folder also appears in history for up to 30 days. Deleting that entry, or clearing history, deletes its file. When the entry expires, the file stays. A file you name with --output never appears in history. Turning off history doesn’t stop Transcription from saving files. They don’t get history’s private-file protections, so delete them when you no longer need them.

Model

Transcription uses your speech model. If it can’t run that model, it uses Parakeet. If Parakeet isn’t on your Mac either, add the Moonshine Base model for English audio. Setup doesn’t download it for you.

1. Download the model’s three files:

   mkdir -p ~/.aria/models/moonshine/base
   cd ~/.aria/models/moonshine/base
   base=https://huggingface.co/onnx-community/moonshine-base-ONNX/resolve/b1e9b6aae3c3c7298f10c3798393fdf38e8fbbad
   curl -fLO "$base/onnx/encoder_model.onnx"
   curl -fLO "$base/onnx/decoder_model_merged.onnx"
   curl -fLO "$base/tokenizer.json"
   

2. Add this section to ~/.aria/settings.toml, or edit the transcription section there:

   [transcription]
   backend = "moonshine"
   model = "~/.aria/models/moonshine/base"
   

3. Run aria settings check. The next transcription uses the model, with no restart.

Voice profiles can name the speakers. For permission or model failures, see Troubleshooting.

Raycast and tmux

These optional integrations use scripts from the Aria repository. If you installed a release, clone it once and keep that folder:

git clone https://github.com/Farhad-Shabani/aria.git ~/aria

The scripts use an installed aria when found, otherwise the checkout’s target/release/aria.

Raycast

In Raycast’s Script Commands settings, add the checkout’s integrations/raycast/ folder as a script directory. Then search for one of these commands:

• Aria Dictate starts manual dictation with live insertion. Set output to an insertion mode under Settings → Dictation first; it cannot use Copy output. Run the command again to stop. For copying, use the next command.
• Aria Dictate to Clipboard copies the completed text. It stops on silence.
• Aria Ask starts a chat. It opens Terminal, records a request, and prints the reply. First, install and sign in to Claude Code or Codex as described in Chat with an assistant.

For insertion, keep an editable field focused in the intended app when opening Raycast and grant Accessibility access. For copying, paste after processing finishes. Dictation follows the same history settings as other recordings.

The helpers start an Aria daemon if none is running. If a command is missing from Raycast, check the script-directory path. If it runs but fails, check aria doctor and which installed or checkout command the helper found.

tmux

The tmux integration shows recording and processing activity in its status bar. It needs both a tmux configuration line and a running watcher.

For a checkout at ~/aria, add this to ~/.tmux.conf. Replace the path if yours is elsewhere:

source-file ~/aria/integrations/tmux/tmux.conf

Reload it from a tmux terminal:

tmux source-file ~/.tmux.conf

If you use the Raycast helpers, they start the watcher. Otherwise run it in another terminal while Aria’s service is running, replacing ~/aria with your checkout path:

~/aria/integrations/tmux/status.sh

Leave that terminal open. The status bar shows a red circle during recording and a processing indicator while Aria finishes the text. It clears when the operation ends.

If the bar stays empty, check the watcher and aria service status. Ctrl-C in the watcher’s terminal stops the display, not dictation. After the service has been stopped for a while, restart the watcher when you start Aria again.

Settings

Aria keeps your settings in ~/.aria/settings.toml. Change them in the Mac app’s Settings window, with aria settings set, or in a text editor. While an Aria window is open, choose File → Open Settings File to edit the file.

Mac app

Open Settings… from Aria’s menu. The sidebar lists these pages:

• General controls launch at login, the status pill, the inline preview, captions, and the speaking rate. Open Assistant here to choose the app and model for Chat and Prompts. Aria Setup reopens setup.
• Dictation sets output, delivery, text cleanup, the microphone, auto-stop, muting sound while recording, and Return sends, which lets Return stop and send. Microphone set to Automatic records with the system’s default input. A microphone you choose records while it’s connected. While it isn’t, Aria records with the default input.
• Recognition sets the language, voice filtering, project vocabulary, and where speech recognition runs.
• Shortcuts chooses right Option or Fn for the Aria key. It also sets what opens Aria and what starts a chat: an Aria key combo, a shortcut of your own, or nothing.
• Prompts lists Markdown files that say what to make of what you say, each with its own shortcut. See Prompts.
• Privacy controls history, retained audio, and memory.
• Phone pairs Aria for iPhone.
• About shows the version and checks for updates.

The language picker offers English, the default, and automatic detection. These choices still depend on the selected model’s supported languages.

Assistant

In Settings → General → Assistant, choose Assistant (Claude Code, Codex, or Local Provider) and Model. Install and sign in first, or set up a local model. Changes apply to the next chat or prompt in both the Mac app and terminal.

Each assistant remembers its own model. Default lets the assistant choose. Local Provider has no default, so it needs a model. Other… accepts a model ID. An unavailable model causes an error, not a switch to another model.

aria settings show assistant.id                     # show the assistant
aria settings set assistant.id codex                # choose claude-code, codex, or local-model
aria assistant models                               # list model IDs
aria settings set assistant.models.codex "MODEL_ID"  # choose a model from the list
aria settings reset assistant.models.codex          # let the assistant choose

Add --assistant codex or --assistant claude-code to list the other assistant’s models. For a single request, use Chat’s options.

Without a choice, Aria uses Claude Code.

Voice speed

For a default speaking rate, use Settings → General → Spoken Content, or run:

aria settings set tts.rate 1.2

This makes speech 1.2 times the normal rate. To change one utterance, use aria say --rate.

Server inference

Run the speech model on a personal server while your desktop records and delivers the text. The desktop needs no local speech model. See Privacy for what gets sent.

On the server, set a local speech model in ~/.aria/settings.toml, then run the command below. The server reads the setting once, so restart aria serve after changing it.

aria serve \
  --bind 0.0.0.0:9851

In another server terminal, create an invitation. Replace your-server with an address your device can reach:

aria remote invite \
  --endpoint https://your-server:9851

Keep the invitation private. It works once, within 60 seconds. Copy it, then pair:

• On a Mac: in Settings → Recognition, click Pair…, then Paste Invitation. Check the address, click Pair, and turn on Recognize speech on your server.
• From a terminal: run aria remote pair, paste it, and press Ctrl-D. Then run aria setup --server.

Either way, the next dictation uses the server, with no restart. Dictation, recorded requests, phone relay and history retries then use the server. Streaming and previews depend on its engine. If the connection fails, the request stops instead of switching to a local engine.

Speech output, wake words and voice profiles stay on the device. Transcription needs its own local transcription.backend. To go back, turn off Recognize speech on your server, or run aria setup --local. Your local engine keeps its settings while the server recognizes speech. If its model isn’t on disk, Aria downloads it before switching back.

To unpair, turn off Recognize speech on your server and click Forget…, or run aria remote forget. The server keeps trusting the device until you block it. Pairing again also waits until speech recognition runs on your device.

To block a device, run aria remote revoke FINGERPRINT on the server. aria remote pair prints the fingerprint. In Settings, Forget… can copy the whole command. If revoking reports a storage error, fix it and revoke again before restarting the server.

Apply changes

Most settings apply to the next dictation or request, including the speech model. Speech output engines, their model paths, the phone port, and other keys marked restart apply after a restart. Check the file and see each value:

aria settings check
aria settings show
aria settings show tts.rate

For dictation.delivery_mode, show also says when dictation delivers after recording stops anyway, such as with copy output or a model that can’t type while you speak.

If the file isn’t valid, Aria keeps your last good settings. On a Mac, Finish Setting Up Aria in Settings names the line when there is one. A service that’s starting won’t run until you fix it.

To change one key without an editor, or return it to its default:

aria settings set memory.enabled on
aria settings reset memory.enabled

A switch takes on, off, true, or false. Name a table’s entry with a dotted path, and quote a bundle ID: aria settings set 'application_overrides."com.apple.Terminal".excluded' on.

Some keys only work together, so set them in one command:

aria settings set \
  stt.backend parakeet-mlx \
  stt.interpreter /usr/bin/python3

In the Mac app, click Restart to Apply. In a terminal, restart the service:

aria service stop
aria service start
aria service status

Restart it too after installing a tool such as claude. On a Mac, Aria reads your shell’s PATH each time it starts. On Linux, the service keeps the PATH it was installed with, so run aria service install again. Do the same if the aria binary moves.

Other settings

Use the annotated settings file for the full reference. aria settings schema prints a JSON Schema for your editor.

Privacy

Aria processes dictation and speech generation locally by default. Local processing does not mean nothing is saved: history is on by default, and text can also reach your clipboard, other apps, and files.

Dictations

History explains saving and retention controls. Turning saving off affects future dictations, not existing entries. Retained original audio can include background voices, even when a voice filter excludes them from the text.

Recording also uses temporary plaintext audio files. Aria deletes them when it no longer needs them. File deletion is not secure erasure and cannot remove backups or snapshots.

On a Mac, Mute while recording asks macOS to silence other apps. Aria doesn’t record, save, or send their sound.

Text cleanup with a local model

When you set a local model, Aria sends the completed text of each dictation to that server. Aria connects only to an address on your own Mac. The server decides where the text goes next. A proxy or a cloud model, such as Ollama’s cloud models, sends it off your Mac. Any program running under your account could listen on that port and read the text. What the server keeps is up to the server.

Server inference

When you use a server, your audio goes to it for recognition. Whoever runs that server can hear the audio and read the text. Pairing alone sends nothing; uploads start only when you switch recognition to the server.

Your voice profile and corrections never leave your computer. Only type my voice checks the speaker before upload when you deliver After recording stops and when you retry from history. With While speaking, audio leaves before Aria knows who spoke. The check helps recognition; it cannot promise that other voices are left out.

The server keeps no history. It deletes its working copies when each recognition ends, though crashes and backups can keep them. Encryption protects audio on the way, not from the person running the server. Pairing keys sit unencrypted in ~/.aria/inference/, readable only by your account.

To stop uploads, turn off Recognize speech on your server in Settings → Recognition, or run aria setup --local. Cancelling a dictation or revoking your device stops what comes next. Neither can take back audio the server already has.

Clipboard and apps

Copying exposes text to apps and clipboard managers that can read your clipboard. Typing inserts it into the focused app, which controls its own saving and sharing. Cancelling Aria cannot recall text already delivered.

On Linux, Aria pastes through the clipboard and the selection, so text it inserts stays on both. Aria asks clipboard managers to skip it, but they may not. The udev rule that lets the hotkey read your keyboard lets every program you run read every key and inject input too. Aria reads key presses only to tell its hotkey apart from typing, and never records what you type.

On a Mac, Aria sees which keys you press, to notice the Aria key. It never records what you type.

To place spaces, Aria reads two characters before the cursor and one after it. It skips password fields and never saves or logs them.

Chats

Chat sends your request to the assistant you choose. Claude Code and Codex may send the request and project content to cloud services. They also keep their own conversation records. Aria uses read-only settings to limit file changes, but those settings don’t prevent network access.

Local Provider sends your request to the server that provider.endpoint names. The server decides where it goes next, as with text cleanup. With history on, each request also carries the chat so far.

With history on, Aria also saves each request and its reply in history for up to 30 days. Starting fresh doesn’t delete earlier records. Clearing Aria’s history, or deleting a chat from it, doesn’t delete the assistant’s records. Deleting a chat also deletes the ID Aria uses to continue that chat with the assistant.

A chat you start from a history entry or a prompt result sends that text to the assistant with your first question. Aria sends it again whenever the chat starts a new assistant session. With history on, Aria saves one copy with the chat. With history off, Aria keeps it in memory until you delete the chat or Aria restarts. Deleting the entry or the result doesn’t delete the copy. Deleting the chat does.

Aria names a chat started on a Mac after its first question, or after the first line of the text it quotes. Clearing history doesn’t remove that name from ~/.aria, and expiry doesn’t either. Deleting the chat does.

Prompts

Prompts send your spoken words as text, along with the prompt file’s instructions, to Claude Code or Codex. A prompt you run on a history entry sends that entry’s text instead: a chat’s reply, or a transcript’s whole text. The assistant may send that text to cloud services.

With history on, Aria saves the result of a prompt you run on a history entry under that entry. Aria deletes it with the entry.

Each run starts without a project, earlier conversation, or Aria memory. Aria also disables the assistant’s tools and leaves out its saved instructions and settings. Prompt recordings are not kept in dictation history.

Memory

Memory is off by default. Turn it on in Settings → Privacy. On a Mac, Aria asks you to confirm first.

With Memory on, Aria saves the text of each request you speak in your own voice. It sends that text to Claude to find facts about you and words Aria mishears. Aria adds those facts to later chats. This includes Local Provider chats, so their text reaches Claude too. Memory needs your voice profile. Without one, Aria saves nothing.

Memory lives in ~/.aria/memory/, or the folder memory.dir names. Only your user account and administrators can read it. Aria deletes a saved request once it’s 30 days old and Aria has checked it for facts. Facts and learned substitutions stay until you delete them.

Turning Memory off keeps what’s stored. To delete it, run aria memory clear. This keeps lexicon.txt and assistant conversations. Deletion isn’t secure erasure and can’t remove backups.

Updates

The Mac app checks GitHub for a new release about once a day. The check sends the request GitHub sees from any download, such as your IP address and the app version. Turn it off in Settings → About with Automatically check for updates.

Files and folders

~/.aria/settings.toml holds engine and model choices, shortcuts, prompt names and paths, and per-app choices. It holds no recordings, transcripts, or credentials. Only your user account and administrators can read it. A paired phone can change only language, output, voice filtering, project vocabulary, and history settings.

Transcripts are separate files with no automatic expiry. History lists transcripts saved under the default folder, and deleting one there deletes its file. Choose a folder with suitable permissions and sharing settings. Delete the files when you no longer need them.

Project vocabulary scans the folder you choose. Its cache contains collected names and source locations. Disabling corrections keeps the cache; forgetting a folder removes its cached names.

Voice profiles store a numeric representation of enrolled speech locally. They are recognition aids, not a way to authenticate a user or guarantee that other voices are excluded. A profile can still identify your voice, so treat it as personal data. Backups of your home folder, such as Time Machine, include it.

Troubleshooting

Start with the symptom you see.

Command not found

On a Mac, finish Aria Setup in Settings → General; it installs the command (see installation). On Linux, make sure ~/.local/bin is on your PATH. Then open a new terminal and try aria --help.

Service unavailable

aria service status

If registered but stopped, run aria service start. If not registered, complete aria setup. For the Mac app, opening Aria starts its background service; choosing Quit Aria stops it.

The background service can’t start without the speech model your settings choose, or Parakeet if they choose none. On a Mac, open Settings and click Download in Finish Setting Up Aria. On Linux, run aria setup. Setup reuses models you already downloaded.

No recording

Run aria doctor for model-path and input-device problems. It doesn’t record to prove microphone access, and it checks only the system’s default input.

Make sure the intended microphone is connected. On a Mac, check Settings → Dictation → Microphone. With Automatic, Aria records with the system’s default input. Elsewhere, dictation.microphone in ~/.aria/settings.toml holds the same choice.

On a Mac, check System Settings → Privacy & Security → Microphone for the app or executable requesting access. Grant permission, then retry. A model file that is missing or unreadable needs to be corrected in setup or Settings.

No inserted text

If recording works but text does not appear, keep the target app and editable field focused. Check Accessibility permission. For a terminal recording, try aria dictate --mode copy and paste to separate insertion from recognition.

On Linux, run aria doctor if the hotkey does nothing; it shows how to grant keyboard access. If text is copied but not pasted, your desktop may lack a remote desktop portal, or you declined its dialog; restart the service to be asked again. Keep the background service running so clipboard text remains available. If the service started outside your desktop, such as over SSH, restart it from the desktop so it can reach the display.

Restart

After changing a speech output engine or another key marked restart, restart the service. Reopening the Mac app also starts it.

No speech output

Check your output device and volume. Then use aria service status and aria settings show to inspect the voice and model paths. Engine and model changes need a restart. aria doctor doesn’t check text-to-speech files.

Linux system speech needs /usr/bin/espeak-ng or /usr/bin/espeak. For Kokoro, rerun setup to obtain its model and voices file, or correct their paths. Dictation keeps working while the Kokoro or Qwen model is missing. With fallback off, the next aria say loads a model you restore at the same path. If you change the path, or the system voice is standing in, restart Aria.

Chat can’t start

Check that your chosen claude or codex command works directly with your account. If you installed it after Aria started, restart the service. On Linux, if it lives outside the service’s saved PATH, run aria service install so the service can find it.

On a Mac, Settings → Assistant marks an assistant that is not installed or not signed in, and shows how to fix it. After you sign in, switch back to Settings and it checks again. A chat that fails for either reason says so in the status pill.

Try a typed request before a spoken one. If typing works but speech doesn’t, check the microphone and speech model.

Transcription fails

In System Settings → Privacy & Security → Screen & System Audio Recording, check permission for the requesting app or executable. Microphone permission doesn’t grant access to your Mac’s audio.

If Transcription can’t run your speech model, it uses Parakeet. Without Parakeet, set up the Moonshine model. For a failure after a transcription starts, run aria transcribe status. Confirm that audio is playing through your Mac.

Read the error

aria wake log shows recent background-service errors, even when wake-word monitoring is off. Look for the failure associated with the operation you tried. After fixing a settings error, apply the change.