Spokenly CLI (Command Line)
Transcribe audio and video files, answer AI agent questions by voice, and manage word replacements with the spokenly command on Mac.
- Mac
- Not available on iPhone
- Not available on Windows
- Not available on Linux
- Not available on Android
The spokenly command transcribes audio and video files, records your spoken answers to AI agents, and manages your word replacements from the terminal.
It needs the Mac app from spokenly.app. The Mac App Store version does not have the CLI. The command works only while Spokenly is running.
Install
Click Install CLI
Open Settings > Privacy & Updates. At the bottom, click Install CLI.
Enter your Mac password
macOS asks for your password, because Spokenly adds a link to the spokenly command in /usr/local/bin. Spokenly gets no other permissions.
Run it
In any terminal, run spokenly transcribe <file>.
Usage
spokenly transcribe <file...> [options]
spokenly ask <question...>
spokenly replacements <list|add|remove>spokenly --version prints the version, and spokenly --help prints the help.
Voice answers for AI agents
spokenly ask shows each question in Spokenly, records your spoken answer and prints the answers as text. Use it with AI agents that can run terminal commands but do not support MCP. If your agent supports MCP, use Voice for Agents instead.
spokenly ask "Deploy to production?" "Anything else to change?"For each question, speak your answer and press Enter. To skip a question, press your cancel shortcut (Escape by default). The command prints Q: and A: blocks:
Q: Deploy to production?
A: Yes, go ahead.
Q: Anything else to change?
A: No, that's all.An answer can take minutes, so the agent must run the command with a timeout of at least 10 minutes. If the process stops earlier, Spokenly cancels the recording and the answer is lost.
To make an agent use the command, add an instruction to its config file, for example ~/.claude/CLAUDE.md for Claude Code:
ALWAYS ask questions by running `spokenly ask "<question>"` in the shell with a 10-minute timeout, never as plain text. I use Spokenly for voice input.Agent skill
Instead of your own instruction, you can install the ready skill (view SKILL.md). It tells the agent when to use spokenly ask, how to read the answers and how to transcribe files with spokenly transcribe.
Claude Code:
mkdir -p ~/.claude/skills/spokenly && curl -fsSL https://spokenly.app/docs/macos/cli/SKILL.md -o ~/.claude/skills/spokenly/SKILL.mdCodex:
mkdir -p ~/.codex/skills/spokenly && curl -fsSL https://spokenly.app/docs/macos/cli/SKILL.md -o ~/.codex/skills/spokenly/SKILL.mdTranscription
spokenly transcribe prints the text of one or more audio or video files.
Options
| Flag | Description |
|---|---|
-f, --format <fmt> | Output format: text (default), srt, vtt, markdown or json |
-s, --speakers | Add speaker labels |
-c, --channels | Transcribe each channel of a multichannel file separately, one speaker per channel. Adds speaker labels |
-n, --names <names> | Speaker names, separated by commas. Needs --channels or --speakers |
Separate channels
Some recordings keep each person on a separate channel, for example a meeting recorder that saves your microphone on one channel and the call on the other. --channels transcribes each channel separately and merges the text in time order. Each channel gets its own speaker label, so Spokenly does not need to tell voices apart.
spokenly transcribe meeting.wav --channelsLeft channel: Hi Bob, I pushed the new release notes to the shared folder this morning.
Right channel: Thanks Alice, I will review them right after the standup meeting today.In a two-channel file, the labels are Left channel and Right channel. With more channels, they are Channel 1, Channel 2 and so on. To use your own labels, add --names in channel order:
spokenly transcribe meeting.wav --channels --names Alice,BobAlice: Hi Bob, I pushed the new release notes to the shared folder this morning.
Bob: Thanks Alice, I will review them right after the standup meeting today.With --speakers, --names labels the speakers in the order in which they first speak:
spokenly transcribe interview.mp3 --speakers --names Alice,BobExamples
Transcribe a meeting recording:
spokenly transcribe meeting.mp3Get VTT subtitles with speaker labels:
spokenly transcribe interview.mp3 --format vtt --speakersCopy the text to the clipboard:
spokenly transcribe meeting.mp3 | pbcopyTranscribe several files into Markdown:
spokenly transcribe part1.mp3 part2.mp3 --format markdownGet the segment texts from JSON:
spokenly transcribe meeting.mp3 --format json | jq '.segments[].text'Model
The CLI uses the model that you select in Transcribe File. With a local model, the file stays on your Mac. With a cloud model, Spokenly uploads the audio for transcription.
--speakers without --channels always uploads the audio to find the speakers, even if you select a local model.
JSON output schema
--format json prints the ID of the model and the list of timed segments. Times are in seconds. Segments get speakerId only with --speakers or --channels.
{
"modelId" : "parakeetTDT06V2",
"segments" : [
{
"end" : 1.42,
"id" : "B7A7C2F3-1E0D-4B6A-9F5C-8C2E5D1A3B4F",
"start" : 0,
"text" : "Hello world."
}
]
}Word replacements
Manage your Word Replacements from the terminal.
spokenly replacements list
spokenly replacements add <original> <replacement> [--regex] [--timing before-ai|after-ai|both]
spokenly replacements remove <original>listprints all replacements as JSON, in the format that the Word Replacements editor exports and imports. You can save the output as a backup and import it later.addadds a replacement. Matching ignores letter case, and an original with commas matches each variant.--regexreads the original as a regular expression.--timingsets when the replacement runs relative to AI processing:before-ai(default),after-aiorboth.removeremoves every replacement whose original text is the same as the value, in any letter case.
spokenly replacements add "air pods" "AirPods"
spokenly replacements add "cloud code, clod code" "Claude Code"
spokenly replacements remove "air pods"
spokenly replacements list | jq '.[].original'To open the add form from another app, use the word replacements deeplink.
Uninstall
Open Settings > Privacy & Updates. Click Uninstall CLI, and Spokenly removes the command from /usr/local/bin.