Command-Line Interface

One Homebrew install. Let Claude Code, Codex, or any AI agent drive transcription, search, and AI rewrites from their terminal.

vivadicta is the official command-line interface for VivaDicta for Mac. It exposes the same data the MCP server does - transcriptions, presets, tags, Viva Modes - plus writes (rewrite, transcribe, poll jobs) so AI coding agents like Claude Code, Codex CLI, and Cursor can drive your dictation history from inside their terminals.

Install

Prerequisite: VivaDicta.app installed at /Applications/VivaDicta.app (download the DMG from vivadicta.com).

brew install n0an/tap/vivadicta
vivadicta recent 5

That installs a tiny bash shim at /opt/homebrew/bin/vivadicta that re-enters the app binary in CLI mode. No background daemon. Upgrades via brew upgrade vivadicta.

Skip Homebrew if you prefer - the same subcommands work via the full path:

/Applications/VivaDicta.app/Contents/MacOS/VivaDicta --cli recent 5

Subcommands

Command	Kind	Purpose
`recent [N]`	read	Last N transcriptions (default 10)
`search <query>`	read	Full-text search with `--since`, `--tag`, `--source`, `--mode`, `--limit`
`get <id-or-query>`	read	Fetch one by UUID or natural-language query
`presets`	read	AI rewrite presets (built-in + custom)
`tags`	read	User tags and source tags with counts
`modes`	read	Viva Modes (app-/URL-aware profiles)
`vocab`	read	Custom vocabulary words
`replacements`	read	Post-transcription find-and-replace rules
`rewrite <id-or-query> --preset P`	write	Apply an AI preset to a transcription
`transcribe <file-or-url> [--async]`	write	Transcribe a local audio file or YouTube URL
`job <uuid>`	write	Poll an async transcription job

Run vivadicta <subcommand> --help for the full flag reference on any subcommand - the binary is the authoritative source and always matches the app version you have installed.

Reads vs Writes

Reads work headlessly. The CLI opens the SwiftData store read-only in-process. You can run vivadicta recent even if the app is completely quit.
Writes require the running app. rewrite, transcribe, and job route through a Unix-domain socket into the running VivaDicta instance, which owns the model cache and provider credentials. If the app isn't open, writes fail with a clear error.

Output Formats

Every subcommand honours four global flags to control output:

--output text - human-readable (default on a TTY)
--output table - aligned columns, good for less
--output json - structured (default when piped), add --pretty to indent
--output markdown - YAML frontmatter + body, ready for an Obsidian vault or GitHub

TTY detection is automatic. Override with the env vars VIVADICTA_FORCE_TTY=1 or VIVADICTA_FORCE_NON_TTY=1.

--quiet / -q suppresses headers. --verbose / -v adds extra fields in text output.

Recipes for AI Agents

Once vivadicta is on $PATH, any coding agent with shell access can use these. Pair with the skill pack so the agent knows when to reach for them without you spelling it out.

Claude Code / Codex: “turn yesterday's standup into action items”

vivadicta rewrite "yesterday standup" --preset action-points

The agent resolves the natural-language query against your history, picks the right preset, and hands you back the rewrite without any clicks in the VivaDicta UI.

Claude Code: “summarise the last 5 notes as JSON so I can feed them to another prompt”

vivadicta recent 5 --output json

Structured output makes it trivial for the agent to loop over results or pipe them into another tool.

Cursor / Codex: “transcribe this YouTube link and summarise”

vivadicta transcribe https://www.youtube.com/watch?v=XXXX
vivadicta rewrite latest --preset summary

Two calls, fully chainable. The agent can watch the first exit code and only run the rewrite if transcription succeeded.

Any agent: “find the note where I talked about the Q4 roadmap”

vivadicta search "Q4 roadmap" --since 30d --output json

Long file, async + polling

JOB=$(vivadicta transcribe ~/Recordings/interview.m4a --async --output json | jq -r .jobId)
vivadicta job "$JOB"   # poll until status is done

Export to markdown (for Obsidian, Git-based notes, anything)

vivadicta get latest --output markdown > ~/vault/inbox/$(date +%Y-%m-%d).md

Driving It From an AI Assistant

The official CLI skill pack teaches Claude Code, Cursor, Codex, Gemini CLI, Pi and any stdio agent how to pick the right vivadicta command and flag combo for the user's intent:

npx skills add n0an/vivadicta-cli-skills --global

Troubleshooting

error: VivaDicta.app not found - install the DMG to /Applications/VivaDicta.app. The shim hardcodes that path.
Writes fail with a socket error - launch VivaDicta. Reads work while the app is quit; writes don't.
JSON output looks different from the docs - run vivadicta --version and upgrade via brew upgrade vivadicta. CLI schemas track the app version.

MCP Server - same data in your AI assistant instead of the shell.
CLI Skills - agent playbooks for the CLI.
n0an/vivadicta-cli - the Homebrew shim source.