VoiceInk Custom Commands: send your dictation to a script instead of pasting it
By Ryleigh Newman · Published
Custom Command is one of VoiceInk's output modes. Instead of pasting, VoiceInk hands the finished text of a dictation to a shell command you write, and that command decides what happens: append it to a note, open a search, call your own script, or post it to a service you run. It is the most flexible thing VoiceInk does with text, and it has a few hard limits worth knowing before you build on it.
I built YapToText, a different dictation app for the Mac, so read what I say about VoiceInk with that in mind. Every fact about VoiceInk here comes from its own docs, read on October 10, 2026.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
This guide in other languages: العربية, Čeština, Dansk, Deutsch, Ελληνικά, Español, Suomi, Français, עברית, हिन्दी, Magyar, Bahasa Indonesia, Italiano, 日本語, 한국어, Norsk, Nederlands, Polski, Português, Română, Русский, Slovenčina, Svenska, ไทย, Türkçe, Українська, Tiếng Việt, 简体中文, 繁體中文
On this page: 8 sections
What the command receives
VoiceInk sends the same final text two ways: on standard input, and in the variable $VOICEINK_TRANSCRIPT. The text is UTF-8, and the docs ask you to quote the variable so spaces, punctuation and line breaks survive.
- AI Enhancement off. The transcript after VoiceInk's formatting and word replacements.
- AI Enhancement on and working. The enhanced text.
- AI Enhancement skipped or failed. The plain final transcript.
The command never gets the audio, the prompt, or the selected, clipboard or screen text directly. If you want context to shape the result, the docs say to use a prompt and Context Awareness, so it is already in the final text.
How it runs
From VoiceInk's docs, Custom Commands, read October 10, 2026.
| Detail | Behavior |
|---|---|
| Shell | /bin/zsh -lc |
| Timeout | 10 seconds, then VoiceInk stops the command |
| Permissions | The same macOS user permissions as VoiceInk |
| Recorder | Dismissed before the command starts |
| Success | Exit code 0. Anything else counts as a failure |
| Output | Standard output and errors are kept for diagnostics, never pasted into the app |
| Commands not found | VoiceInk tries your shell PATH. Use a full path such as /opt/homebrew/bin/tool if it fails |
The limits that catch people
- Nothing is pasted for you. If you still want the text in the app, your command has to copy or paste it itself.
- Ten seconds, no questions. The command cannot wait for input. For longer work, start your own background process and exit quickly.
- It does not change the saved transcript. Whatever the command prints is not written back.
- No Auto Send. Auto Send works only with Paste output, not with Custom Command.
- Live dictation only. Files in the Transcribe file queue are saved without running output commands.
- No empty command. A Mode with an empty command cannot be saved.
The built-in templates
From VoiceInk's docs, Custom Commands, read October 10, 2026.
| Template | What it does |
|---|---|
| Paste and Press Tab | Copies the text, pastes it, then presses Tab |
| Lowercase and Paste | Lowercases the text, copies it, then pastes it |
| Remove Trailing Period and Paste | Drops one final period before pasting |
| Append to Journal | Adds the text to ~/Documents/VoiceInk/journal.md |
| Search Web | Opens a web search for the text |
The docs suggest starting from a template and editing it. Two of their simplest examples, copying the text and appending it to a note:
printf "%s" "$VOICEINK_TRANSCRIPT" | pbcopymkdir -p "$HOME/Documents/VoiceInk"
printf -- "- %s\n" "$VOICEINK_TRANSCRIPT" >> "$HOME/Documents/VoiceInk/notes.md"Checking whether it worked
VoiceInk shows no success or failure message after a Custom Command. The docs give a Terminal command that shows the last 10 minutes of delivery logs, including whether the command succeeded, failed or ran past 10 seconds:
/usr/bin/log show --last 10m --style compact \
--predicate 'subsystem == "com.prakashjoshipax.voiceink" AND category == "TranscriptionDelivery"'The docs warn that these logs can contain dictated text. And if your command sends text to a web service, that service receives it: VoiceInk only runs what you configured.
Where YapToText stands
VoiceInk from its docs, read October 10, 2026. YapToText from its own settings.
| VoiceInk | YapToText | |
|---|---|---|
| Run a shell command with the text | Yes, Custom Command output | No |
| Paste at the cursor | Paste output | Paste, the default |
| Type it instead | Not described on this page | Type character by character |
| Clipboard only | With a command such as pbcopy | Copy to clipboard only |
| Press a key after | Paste and Press Tab template | Return or Command Return per app |
| Review before it lands | Not described on this page | Review before inserting, off by default |
If you want dictation to drive your own scripts, VoiceInk's Custom Command does something YapToText does not. If you want text at the cursor, shaped to the words around it, YapToText does that by default and needs no script. The VoiceInk Modes page covers where output modes are set, and VoiceInk against superwhisper compares it with another app built around modes.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
The short version
- What it is. An output mode that runs your shell command with the final text.
- The text. On standard input and in $VOICEINK_TRANSCRIPT.
- Limits. 10 seconds, no input, no automatic paste, live dictation only.
- Debugging. No message in the app. Read the log with the Terminal command above.
- Start here. Edit one of the five templates.
If VoiceInk changes how Custom Commands work, open an issue on GitHub and I will update this page. Every one gets read.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
Related
Sources
- https://tryvoiceink.com/docs/custom-commands (checked 2026-10-10)
- https://tryvoiceink.com/docs/mode-settings (checked 2026-10-10)
- https://github.com/ryleighnewman/YapToText (checked 2026-10-10)
- https://apps.apple.com/us/app/yaptotext/id6786382289 (checked 2026-10-10)
Questions
What is a Custom Command in VoiceInk?
An output mode. Instead of pasting, VoiceInk runs a shell command you write and passes it the final text of the dictation.
How does a VoiceInk Custom Command get the text?
On standard input and in the variable $VOICEINK_TRANSCRIPT, as UTF-8. Quote the variable to keep spaces and line breaks.
Why did my VoiceInk Custom Command not paste anything?
Custom Command output does not paste on its own. Your command has to copy or paste the text itself, as the Paste and Press Tab template does.
How long can a VoiceInk Custom Command run?
10 seconds. After that VoiceInk stops it. Start a background process for longer work.
Does YapToText have custom commands like VoiceInk?
It does not run shell commands after a dictation. It pastes or types at the cursor, can copy to the clipboard only, and can press Return after the text lands.