Spokenly CLI (Command Line)

The spokenly CLI lets you transcribe audio and video files and manage your word replacements directly from your terminal. It connects to the Spokenly app running on your Mac and returns plain text, SRT, VTT, Markdown, or JSON output.

Install

Usage

spokenly transcribe <file...> [options]

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'

Check the installed CLI version:

spokenly --version

Transcription 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 > Settings > General and click Uninstall CLI. This removes the command from /usr/local/bin.