Spokenly CLI (Command Line)

The spokenly CLI lets you transcribe audio and video files and manage your word replacements from your terminal. AI agents can also run it to ask you questions and get your spoken answers back as text. It connects to the Spokenly app running on your Mac. Transcriptions can be returned as plain text, SRT, VTT, Markdown, or JSON.

Install

Usage

spokenly transcribe <file...> [options]
spokenly ask <question...>
spokenly replacements <list|add|remove>

ask and replacements are covered in their own sections below. spokenly --version prints the installed CLI version.

Voice Answers for AI Agents

spokenly ask shows you questions in Spokenly, records your spoken answers, and prints them to stdout. It is built for AI agents that can run shell commands but do not support MCP: the agent runs the command, you answer by speaking, and the transcribed answers go back to the agent.

spokenly ask <question...>

Each question starts a recording session in Spokenly. Speak your answer and press Enter, or press Escape to skip it. Answering can take minutes, so the agent must run the command with a timeout of at least 10 minutes. If the process is killed earlier, the recording is canceled and the answer is lost.

spokenly ask "Deploy to production?" "Anything else to change?"

Answers are printed as Q: / A: blocks:

Q: Deploy to production?
A: Yes, go ahead.

Q: Anything else to change?
A: No, that's all.

To get an agent to use it, add an instruction like this 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.

If your tool supports MCP, use the MCP integration instead.

Agent Skill

Instead of writing your own instructions, install the ready-made skill (view SKILL.md). It tells the agent when to use spokenly ask, how to handle its responses, 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.md

Codex:

mkdir -p ~/.codex/skills/spokenly && curl -fsSL https://spokenly.app/docs/macos/cli/SKILL.md -o ~/.codex/skills/spokenly/SKILL.md

Transcription

Options

Separate channels

If your recording keeps each participant on their own channel, for example a meeting recorder that captures the local microphone on one channel and the remote call audio on another, --channels transcribes every channel on its own and merges the results in time order. Each channel becomes its own speaker, so you never need diarization to tell participants apart.

spokenly transcribe meeting.wav --channels

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

Two-channel files are labeled Left channel and Right channel. Files with more channels are labeled Channel 1, Channel 2, and so on. Pass --names to use your own labels, given in channel order:

spokenly transcribe meeting.wav --channels --names Alice,Bob

Alice: 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.

--names also works with --speakers, where the names are applied to the detected speakers in order of first appearance:

spokenly transcribe interview.mp3 --speakers --names Alice,Bob

If every channel turns out to contain the same audio, which happens when a stereo file is just one source duplicated, Spokenly transcribes a single channel to avoid duplicated text and prints a note to stderr.

Examples

Transcribe a meeting recording:

spokenly transcribe meeting.mp3

Transcribe with speaker labels in VTT format:

spokenly transcribe interview.mp3 --format vtt --speakers

Transcribe a two-channel meeting recording with named participants:

spokenly transcribe meeting.wav --channels --names Alice,Bob

Pipe output to clipboard:

spokenly transcribe meeting.mp3 | pbcopy

Transcribe multiple files:

spokenly transcribe part1.mp3 part2.mp3 --format markdown

Get JSON with segment timestamps for downstream tooling:

spokenly transcribe meeting.mp3 --format json | jq '.segments[].text'

Model

The CLI uses the model selected in the Transcribe File section of the app. If you have a local model like NVIDIA Parakeet selected, transcription runs entirely on your Mac. Otherwise, the file is sent to the Spokenly server for online transcription.

JSON Output Schema

The --format json flag returns a pretty-printed JSON object with the model used and an array of timed segments. speakerId is only populated when --speakers or --channels is passed.

{
  "modelId": {
    "predefined": "parakeetTDT06V2"
  },
  "segments": [
    {
      "id": "B7A7C2F3-1E0D-4B6A-9F5C-8C2E5D1A3B4F",
      "text": "Hello world.",
      "start": 0.0,
      "end": 1.42,
      "speakerId": null
    }
  ]
}

Word Replacements

Manage your Word Replacements from the terminal. The app must be running.

spokenly replacements list
spokenly replacements add <original> <replacement> [--regex] [--timing before-ai|after-ai|both]
spokenly replacements remove <original>

list prints the full list as JSON, in the same format the Word Replacements editor exports and imports, so you can pipe it to jq or save the output as a backup and import it back later.

add creates a replacement. Matching is case-insensitive, and a comma-separated original matches each listed variant. Pass --regex to treat the original as a regular expression, and --timing to control when the replacement runs relative to AI formatting (before-ai is the default).

remove deletes every replacement whose original text equals the given value, case-insensitively.

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 pre-fill the add form from another app instead of scripting, use the word replacements deeplink.

Uninstall

Open Spokenly > General Settings and click Uninstall CLI. This removes the command from /usr/local/bin.