Welcome to Aria

Aria lets you type by speaking, hear text read aloud, and ask questions about a project. On a Mac, you can dictate into other apps with a hotkey. On Linux, use the terminal to record speech and copy the text.

Start here

Install Aria, then try Mac 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.
• Ask a question through Claude Code or Codex.
• 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 on your machine. Downloading models needs network access. Ask uses an external agent, which may send your question and project content to cloud services.

Dictation history is enabled 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 the macos-arm64 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. Express Setup uses the defaults; Customize… lets you choose engines and models.

To use the aria command in a terminal too, add this line to ~/.zshrc, then open a new terminal:

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.

Aria needs a systemd user session for its background service and ALSA (libasound2) for audio. For copying text, run it in your graphical desktop session. For speech output, install a system voice:

sudo apt-get install espeak-ng

Continue to terminal dictation.

Setup

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

aria setup

Choose Whisper for a first transcription. Setup can download its model. For speech output, the system voice needs no model. You can leave optional features at their defaults. Choosing a chat agent does not contact it; an agent account is needed only for Ask.

Setup saves ~/.aria/config.yaml, downloads the models you select, and starts Aria’s background service. It backs up a hand-written configuration as config.yaml.bak before updating it. If a model download is interrupted, rerun setup to resume it.

To check the result:

aria doctor

Doctor reports configuration, model-path, and service problems. It does not record audio to test microphone permission.

Update or remove

On a Mac, choose Quit Aria from its menu, replace Aria in Applications with the copy from the new DMG, and open it. To remove Aria, quit it and move it to the Trash. With Homebrew, run brew upgrade --cask aria or brew uninstall --cask aria.

On Linux, rerun the install command to update. To remove Aria:

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

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

Build from source

To build Aria yourself, follow Get started 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. Set Up Aria… reopens setup if you need it.

Permissions

Aria needs two permissions:

• Microphone to hear you. Allow access when macOS asks. If you previously denied it, check System Settings → Privacy & Security → Microphone for the app or executable named in the request.
• Accessibility to read the hotkey and type into other apps. In System Settings → Privacy & Security → Accessibility, click + and choose /Applications/Aria.app/Contents/Helpers/aria. 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.

Recognized 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. Change the key to Fn under Settings → Shortcuts if you prefer.

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

Captions

Enable Show Captions in Aria’s menu to display recognized text while recording. With this option on, Aria types the completed transcript after you stop. With it off, Aria types finalized segments while you speak.

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

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.

Terminal dictation

Use aria dictate to record one utterance and copy the recognized words. Complete setup and keep the background service running. On Linux, the service also keeps copied text available for pasting. Run it in your graphical desktop session so Aria can access the clipboard.

Copy a sentence

aria dictate \
  --mode copy

Say a short sentence, then pause. With the default stop setting, 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 preference. --mode copy chooses the clipboard for this recording without changing that preference.

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 transcription, and copies the result.

Without --toggle, Aria uses your saved stop setting. Recordings stop after five minutes at most.

Mac insertion

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 transcript. --stream types finalized segments while you speak. Use --mode insert-or-copy if you want copying when insertion cannot begin. Linux uses the clipboard and does not support insertion-only modes.

Spoken corrections

To correct a simple change of mind in the completed text, add this setting to ~/.aria/config.yaml and restart the service:

dictation_backtrack: true

For example, “meet me at 3, actually 4” can become “meet me at 4”. “Send it to Ali, scratch that, to Sara” can become “Send it to Sara”. This handles only simple, unambiguous corrections within a clause. More complex corrections stay as spoken.

Corrections apply to the completed transcript. For Mac hotkey dictation, enable Show Captions to deliver after stopping. Live insertion cannot retract earlier text, so it keeps the original words and correction cue.

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

Dictation history

Aria saves completed dictations so you can review their text. These controls apply to both Mac and terminal dictation. Ask conversations and system-audio transcripts are separate.

Saving

Saving is on by default. In the Mac app, turn it off under Settings → General → Save dictation history. This stops future saves and leaves existing entries until you delete them or they expire. The CLI has no control for this preference.

Text is kept for up to 30 days, with limits of 1,000 entries and 8 MiB total. Older entries can disappear sooner when those limits are reached.

By default, only failed transcriptions 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, choose Dictation History… from Aria’s menu. Search for an entry, then select it to read the text. Copy text copies it for use elsewhere.

From a terminal, run:

aria history list

The list shows each entry’s ID, status, recording availability (available, expired, or unavailable), and its full text.

Retry

If an entry still has its recording, choose Retry transcription in the Mac app. 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.

Keep successful recordings

To make future successful dictations available for retry, enable Settings → Dictation → Show Advanced Options → Also retain audio of successful dictations, or run:

aria history retain-audio true

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

To stop keeping future successful recordings:

aria history retain-audio false

Existing recordings continue to expire.

Delete

In the Mac app, select Delete… for one entry or Clear History… for all entries and retained recordings. Clear includes entries outside the current search.

From a terminal:

aria history clear

Answer y or yes to confirm; any other answer cancels. Clearing cannot be undone, and it leaves saving settings unchanged.

Clearing history does not remove clipboard copies, Ask conversations, or system-audio transcript files. Deletion is not secure erasure and cannot remove backups. Read Privacy for the other places text can go.

Read text aloud

Use aria say to play text through your configured 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/config.yaml, using their actual paths. Setup’s default paths are:

tts:
  backend: kokoro
  model: ~/models/kokoro/kokoro.onnx
  voices: ~/models/kokoro/voices.bin
  voice: af_heart
  rate: 1.0

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 cannot initialize, add fallback: system to that tts section. Fallback is off by default and applies when the engine or output cannot start.

If nothing plays, follow speech troubleshooting.

Ask a question

Ask sends a typed or spoken question to Claude Code or Codex and prints the reply in your terminal. It does not read replies aloud.

Your question and project content read by the agent may go to cloud services. Spoken questions are transcribed locally first. The agent keeps its own conversation records. Read Privacy before using private project content.

Before you start

Complete setup, then install and sign in to the claude or codex command you selected. Follow the Claude Code quickstart or Codex CLI setup, then check that the command works with your account. Keep Aria’s background service running.

If you installed the agent after Aria setup, refresh the service registration so it can find the command.

Try a typed question

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

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

Wait for the reply. --project tells the agent which folder to read. Aria uses read-only agent settings; this limits changes to files but does not prevent the agent from reading them or sending content to its service.

To continue the conversation, ask again from the same folder with the same agent:

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

Speak a question

Once the typed question works, omit its text:

aria ask \
  --project "$PWD"

Speak, then pause. With the default stop setting, silence ends the recording. The answer appears in the terminal. If a spoken question fails, try the typed example again to distinguish an agent problem from a recording problem.

Cancel

Press Esc when the terminal shows its cancel prompt to cancel the question.

Start fresh

Repeated questions continue the conversation for that folder and agent. Use --new to start another:

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

Starting fresh does not delete the agent’s earlier conversation records. Use --session with a name if you want separate conversations in one folder. For a different agent on one request, add --agent codex or --agent claude-code.

If Ask cannot start its agent, check Troubleshooting. For names in spoken questions, Project vocabulary explains how to prepare the folder’s spellings.

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 and names found in local text. A .gitignore file does not prevent Aria from reading those files. Aria skips hidden files but does not check other files for secrets. Choose a folder you are comfortable letting Aria read. Names and their source locations stay in a private local cache.

Complete setup and keep the background service running. In the Mac app, enable Settings → Dictation → Show Advanced Options → Use project vocabulary and choose the folder. Or open a terminal in that folder:

aria vocabulary use "$PWD"
aria vocabulary status

Wait until status says its vocabulary is ready. If it is still preparing, check again. Then dictate a project name and inspect its spelling. Ambiguous names stay unchanged.

Refresh

After adding or renaming files, refresh the names:

aria vocabulary refresh
aria vocabulary status

Refresh runs in the background. Aria does not watch the folder for changes.

Which folder applies?

Terminal dictation uses the directory you run it from. Hotkey dictation uses the folder selected with vocabulary use. A folder includes its descendants; Aria does not search upward for a project root.

For a spoken question, aria ask --project "$PWD" uses that folder for both spellings and the answering agent. Ask can send project content to external services; read Ask a question first.

System-audio transcription does not use project vocabulary. Live dictation corrects each finalized segment separately, so a name split across segments may stay unchanged.

Disable or forget

Run aria vocabulary disable to stop corrections while keeping cached names. Use aria dictate --no-project to skip corrections for just one dictation.

To remove names cached for a folder:

aria vocabulary forget "$PWD"

This also removes overlapping parent and child caches. Disable corrections first if you do not want a later refresh to recreate them.

If status reports TooLarge, choose a smaller folder. 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 one complete transcript using your output preference. It does not ask an agent a question.

This keeps microphone monitoring active while the daemon runs. Wake-triggered dictation follows the same history preference 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 ~/models/wakeword as aria.onnx, beside melspectrogram.onnx and embedding_model.onnx.

Enable monitoring in ~/.aria/config.yaml:

wake:
  enabled: true
  backend: openwakeword
  model: ~/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, delivery uses the clipboard.

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 configuration 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 speaker labels are used by Mac system-audio transcription.

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 system-audio 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.

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 → Dictation → Show Advanced Options → Only type my own voice. It is off by default, and the CLI has no control for this preference.

Filtering needs the speaker model and an owner profile. Without the model, live dictation passes all speech through, but a retry reports no speech. Without an owner profile, or when a sample is inconclusive, speech can pass through. Do not rely on it to keep private background speech out of a recording. Retained originals can contain voices excluded from the delivered text.

Other speakers

To add a guest:

aria speaker enroll partner \
  --role guest

Voice profiles can supply speaker labels in system-audio transcripts. Labels may change as more audio arrives, so the saved transcript may differ from the first labels printed in the terminal.

Replace or remove

To replace alex with new recordings, keep its role explicit:

aria speaker enroll alex \
  --role owner \
  --replace

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.

System audio (Mac)

Listen saves a transcript of audio playing on your Mac, such as a meeting or video. It captures system output, not microphone dictation, and writes to a file rather than typing into an app.

This task needs a separate model and permission. First check Mac dictation or terminal dictation, depending on how you installed Aria.

Model

The default Whisper model cannot run Listen. Use the Moonshine Base model below for English audio. Setup does not download this model for you.

1. Download the model’s three files:

   mkdir -p ~/models/moonshine/base
   cd ~/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/config.yaml, or edit its existing listen section:

listen:
  backend: moonshine
  model: ~/models/moonshine/base
  transcripts_dir: ~/.aria/transcripts

Check it with aria config show. The next aria listen start reads it; no restart is needed. Keep Aria’s background service running.

Record

You need two terminals: one to show the transcript and one to stop recording.

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

   aria listen start \
     --follow
   

2. Allow System Audio Recording if macOS asks. The terminal prints listening -> and an output path when the request is accepted. Confirm that recognized text appears as the audio plays.

3. When finished, stop capture in a second terminal:

   aria listen stop
   aria listen status
   

4. Check that status says not listening, then open the file at the path printed when the session started.

Ctrl-C stops the terminal display, not the recording. Always use aria listen stop to end capture. Use aria listen follow to show live text again during a session.

Transcript files

By default, files are saved under ~/.aria/transcripts. To choose another path:

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

If the file exists, Listen appends to it. This command starts a session; do not run it while another session is recording.

These files have no history expiry. Turning off dictation history does not stop Listen from saving them, and clearing history does not delete them. They do not get history’s private-file protections, so delete them yourself when you no longer need them.

Voice profiles can give speakers names. 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 transcript. It uses your saved stop setting, which is silence by default.
• Aria Ask opens Terminal, records a question, and prints the reply. It requires an authenticated agent as described in Ask.

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 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

Use the Mac app’s Settings window for everyday choices. Use ~/.aria/config.yaml for engines, model paths, and service options. App preference changes apply immediately; file changes require a restart.

Mac app

Open Settings… from Aria’s menu:

• General controls launch at login, the status pill, and dictation-history saving.
• Shortcuts chooses right Option or Fn for the dictation hotkey, and sets the Ask shortcut.
• Dictation selects language and output, and can mute your speakers while recording. Show Advanced Options contains delivery, voice filtering, project vocabulary, stopping, and retained audio.

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

Voice speed

For a default speaking rate, open ~/.aria/config.yaml in a text editor. If it already has a tts section, edit that section rather than adding another:

tts:
  rate: 1.2

This makes speech 1.2 times the normal rate. For a change to just one utterance, use aria say --rate.

Apply changes

After editing the file, inspect what your terminal would load:

aria config show

For the example above, find tts.rate and check that it is 1.2. The output shows each setting’s source. It describes this shell’s configuration, not a snapshot of the running service.

Restart the registered service to apply file changes:

aria service stop
aria service start
aria service status

Starting a service that is already running does not reload it.

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 configuration file for the full reference. Unknown fields are rejected. App preferences such as recognition language and history saving do not belong in config.yaml.

Environment variables affect only your terminal, not the background service.

Privacy

Aria processes dictation and speech generation locally. Local processing does not mean nothing is saved: dictation history is on by default, and transcripts 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.

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.

Questions

Ask uses Claude Code or Codex. The agent may send the question and project content to cloud services and retain its own conversations. Aria’s read-only agent settings restrict edits; they do not make the agent offline.

Starting a fresh Ask conversation does not delete earlier records. Clearing Aria’s dictation history does not delete agent conversations.

Files and folders

System-audio transcripts are separate files with no automatic history expiry. 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.

Troubleshooting

Start with the symptom you see.

Command not found

On a Mac, add the app’s command folder to your PATH as shown in 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.

No recording

Run aria doctor for model-path and input-device problems. It does not record to prove microphone access. Make sure the intended microphone is connected and selected as the system’s default input.

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 the actual Aria executable. For a terminal recording, try aria dictate --mode copy and paste to separate insertion from recognition.

On Linux, use copying rather than insertion-only modes. Keep the background service running so clipboard text remains available.

Restart

After changing engine settings, 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 config show to inspect the voice and model paths. File changes require a restart. aria doctor does not check speech-engine 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.

Ask cannot 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.

Try a typed question before a spoken one. If typing works but speech does not, check the microphone and recognition model.

System audio fails

In System Settings → Privacy & Security → Screen & System Audio Recording, check permission for the requesting app or executable. Microphone permission does not grant system-audio access.

The default Whisper model cannot run Listen. Check the Moonshine files and configuration, and use aria listen status for a failure reported after starting. Confirm that audio is actually 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 configuration error, apply the change.