# The `talkie` command

Read your memos, dictations, and captures from the terminal, or hand them to an agent. Output is JSON when piped and a table in the terminal.

Source: https://www.talkie.to/docs/cli

Version: @talkie/cli 0.4.11. Machine-readable: https://www.talkie.to/docs/cli.json

## Install

```sh
bun add -g @talkie/cli
```

The command reads Talkie’s library on this Mac directly, so it works when the app is closed. `talkie mcp` runs it as an MCP server for agents.

## Global options

- `--db <path>`: override database path; capture media is read beside that database (default: production Talkie)
- `--json`: force JSON output (default when piped)
- `--pretty`: force human-readable output (default in terminal)

## Library

### `talkie memos [id]`

List voice memos, or get a specific memo by ID (prefix match)

- `--limit <n>`: max results (default: 50)
- `--since <date>`: filter by date (e.g. 2025-02-01 or 7d)
- `--segments`: show word-level timestamps in detail view

### `talkie dictations [id]`

List recent dictations, or get a specific dictation by ID

- `--limit <n>`: max results (default: 50)
- `--since <date>`: filter by date (e.g. 2025-02-01 or 7d)

### `talkie search [query]`

Search and filter recordings

- `--limit <n>`: max results (default: 20)
- `--type <type>`: filter by type (memo, dictation)
- `--since <date>`: created after date (7d, 24h, 2026-02-01)
- `--until <date>`: created before date
- `--app <name>`: filter by app name or bundle ID
- `--source <src>`: filter by source (mac, iphone, watch, live)
- `--has <field>`: has data: screenshots, clips, videos, captures, summary, tasks, audio, segments
- `--longer-than <seconds>`: minimum duration in seconds
- `--shorter-than <seconds>`: maximum duration in seconds
- `--sort <order>`: sort: newest, oldest, longest, shortest, relevance

### `talkie captures [id]`

List saved screenshots and screen recordings (all sources). Optional argument: capture ID, filename, or path, NOT a count. Use --limit 5 for five results. Does not create a capture.

- `-n, --limit <n>`: max results (default: 50)
- `--since <date>`: filter by capture/file date (e.g. 2026-06-01 or 7d)
- `--kind <kind>`: screenshot, clip, video, or all (default: all)
- `--source <source>`: all, tray (live/legacy tray and buffer), recording (attached to a recording), or library (unattached media files) (default: all)
- `--recording <id>`: filter captures attached to a recording ID prefix
- `--app <name>`: filter by app, window, display, or filename
- `--ocr`: include OCR text when available
- `--path`: print only capture file paths
- `--paths`: print only capture file paths
- `--open`: open the matched capture file(s)
- `--reveal`: reveal the matched capture file(s) in Finder
- `--context`: include visual-context bundle paths and frame canvas metadata
- `--contact-sheet`: print only contact-sheet.jpg paths when available
- `--frames`: print only frames/ directory paths when available

### `talkie screenshots [n]`

List saved still images, newest first, from all sources. Screencap and screengrab mean screenshot, not video. Use --source tray for tray-only results. Does not take a screenshot.

Aliases: `screencaps`, `screen-caps`, `screen-captures`, `screencap`, `screengrab`, `screengrabs`

- `-n, --limit <n>`: max screenshots (default: 5)
- `--since <date>`: filter by capture/file date (e.g. 2026-06-01 or 7d)
- `--source <source>`: all, tray (live/legacy tray and buffer), recording (attached to a recording), or library (unattached media files) (default: all)
- `--all-sources`: include tray, recording, and library screenshots
- `--app <name>`: filter by app, window, display, or filename
- `--ocr`: include OCR text when available
- `--path`: print only screenshot file paths
- `--paths`: print only screenshot file paths
- `--open`: open the matched screenshot file(s)
- `--reveal`: reveal the matched screenshot file(s) in Finder

### `talkie clips [n]`

List saved screen recordings (video), newest first, from all sources. Use clips 1 --paths for the latest video. Use --source tray for tray-only results. Does not start recording.

Aliases: `screen-clips`, `screenclips`, `videos`

- `-n, --limit <n>`: max clips (default: 5)
- `--since <date>`: filter by capture/file date (e.g. 2026-06-01 or 7d)
- `--source <source>`: all, tray (live/legacy tray and buffer), recording (attached to a recording), or library (unattached media files) (default: all)
- `--all-sources`: include tray, recording, and library clips
- `--app <name>`: filter by app, window, display, or filename
- `--path`: print only clip file paths
- `--paths`: print only clip file paths
- `--context`: include visual-context bundle paths and frame canvas metadata
- `--contact-sheet`: print only contact-sheet.jpg paths when available
- `--frames`: print only frames/ directory paths when available
- `--open`: open the matched clip file(s)
- `--reveal`: reveal the matched clip file(s) in Finder

### `talkie stats`

Show app statistics (dictation counts, streaks, word counts)

### `talkie create`

Create a first-class Talkie object

### `talkie create note`

Create a validated Markdown note in the Talkie library

- `--text <markdown>`: inline Markdown content
- `--file <path>`: read Markdown content from a file
- `--stdin`: read Markdown content from standard input
- `--data <json>`: validated JSON note data
- `--title <title>`: note title
- `--source <memo-id>`: source memo UUID
- `--open`: open the created note in Talkie

## Voice

### `talkie dictate`

Toggle TalkieAgent dictation, or insert finished text into the frontmost app

- `--status`: read companion runtime state without toggling dictation
- `--text <text>`: insert text (companion paste-text); does not start the mic
- `--app <bundleID>`: target app bundle ID for --text (default: frontmost)
- `--submit`: press return after inserting --text

### `talkie mic`

Show or change the TalkieAgent dictation microphone

### `talkie mic list`

List input devices and the current microphone

### `talkie mic set <device>`

Pin the dictation microphone by name or uid

### `talkie mic default`

Follow the system default microphone

### `talkie speak <text>`

Speak text aloud via Talkie gateway TTS (OpenAI)

- `--voice <id>`: OpenAI voice (alloy, echo, fable, onyx, nova, shimmer)

## Agents and workflows

### `talkie mcp`

Run a stdio MCP server exposing the Talkie library (read-only)

### `talkie workflows [id]`

List workflow runs, or get details for a specific run

- `--limit <n>`: max results (default: 50)
- `--since <date>`: filter by date (e.g. 2025-02-01 or 7d)
- `--status <status>`: filter by status (completed, failed, running)

### `talkie workflows run <workflowId>`

Run a workflow against a library object via TalkieServer

- `--object <id>`: object id or unique prefix

## iPhone and other devices

### `talkie pair`

Pair an iPhone or iPad with this Mac Bridge

- `--host <host>`: override the local bridge host to contact
- `--port <port>`: override the bridge port (default: 19825)
- `--payload`: print only the raw Talkie Bridge QR payload
- `--no-qr`: skip terminal QR rendering
- `--wait [seconds]`: wait for a newly paired device

### `talkie pair pending`

List pending Mac Bridge pairing requests

- `--host <host>`: override the local bridge host to contact
- `--port <port>`: override the bridge port (default: 19825)

### `talkie pair approve <deviceId>`

Approve a pending Mac Bridge pairing request

- `--host <host>`: override the local bridge host to contact
- `--port <port>`: override the bridge port (default: 19825)

### `talkie pair reject <deviceId>`

Reject a pending Mac Bridge pairing request

- `--host <host>`: override the local bridge host to contact
- `--port <port>`: override the bridge port (default: 19825)

### `talkie companion`

Show the iPhone/iPad companion App Store QR code

Aliases: `barcode`

- `--open`: open the App Store page on this Mac
- `--image`: open a QR image in the browser
- `--url`: print only the App Store URL
- `--qr-url`: print only the QR image URL
- `--no-qr`: skip terminal QR rendering

### `talkie terminal`

Pair the iOS Talkie app for SSH access (works without Talkie.app or TalkieAgent running)

Aliases: `ssh`

### `talkie terminal pair`

Prepare SSH terminal access for the iOS Talkie app and show the import QR

- `--ios-only`: explicit acknowledgement that this pair flow targets the iOS Talkie app (the QR carries a private key for the phone to import) (default: true)
- `--host <host>`: SSH host to save on iPhone/iPad (defaults to Tailscale hostname)
- `--port <port>`: SSH port (default: 22)
- `--username <name>`: SSH username (default: arach)
- `--payload`: print only the raw SSH key payload JSON
- `--link`: print only the talkie:// import link
- `--no-qr`: skip terminal QR rendering
- `--no-helper`: skip installing local Talkie terminal helper scripts
- `--open-settings`: open macOS Remote Login settings after preparing

### `talkie terminal status`

Show SSH terminal pairing status

### `talkie terminal doctor`

Check SSH terminal pairing readiness

### `talkie sync`

TalkieSync — iCloud sync management

### `talkie sync now`

Trigger an immediate sync (incremental by default, syncs since last sync)

- `--limit <n>`: Fetch at most N records
- `--since <date>`: Only records created after this date (ISO 8601 or yyyy-MM-dd)
- `--full`: Full reconciliation of all memos (slow — use sparingly)

### `talkie sync status`

Detailed sync status

### `talkie sync ping`

Check if TalkieSync is reachable

### `talkie sync providers`

List sync providers

### `talkie sync run-pass`

Force a sync pass

## The app

### `talkie open [target]`

Open Talkie.app, or use `talkie open agent` for TalkieAgent

- `--dev`: open the stable local TalkieAgent development build
- `--production`: open the TalkieAgent embedded in /Applications/Talkie.app
- `--restart`: restart TalkieAgent before opening it

### `talkie agent`

Launch TalkieAgent without opening the main Talkie window

- `--dev`: launch the stable local development build
- `--production`: launch the helper embedded in /Applications/Talkie.app
- `--restart`: restart all running TalkieAgent instances before launch

### `talkie install`

Download and install the latest Talkie.app to /Applications

- `--check`: check for updates without installing
- `--target <version>`: install a specific version (e.g. 2.0.23 or v2.0.23)
- `--force`: reinstall even if already on the target version
- `--launch`: launch Talkie after installing
- `--no-restart`: skip restarting Talkie and TalkieAgent after upgrade

### `talkie upgrade`

Upgrade Talkie.app if a newer version is available

Aliases: `update`

- `--check`: check for updates without installing
- `--force`: reinstall even if already on the latest version
- `--launch`: launch Talkie after installing
- `--no-restart`: skip restarting Talkie and TalkieAgent after upgrade

### `talkie uninstall`

Remove Talkie.app from /Applications

### `talkie where`

Show Talkie app, CLI, and data locations

### `talkie doctor`

Check Talkie installation, permissions, services, and local tooling

### `talkie doctor ai`

Diagnose Apple's on-device model (Apple Intelligence), fix what can be fixed, and optionally wait until it's ready

- `--fix`: open the exact System Settings pane for each failing check
- `--wait [seconds]`: poll until the model is ready (default 900s)
- `--smoke`: when ready, run a one-line generation to prove the model works

### `talkie data`

Show where Talkie stores your data and how much space it uses

### `talkie data path`

Print the data folder path

- `--open`: open the folder in Finder

### `talkie data archive`

Back up all Talkie data to a zip file

- `-o, --output <path>`: output path (default: ~/Desktop/talkie-data-<timestamp>.zip)
- `--open`: reveal the archive in Finder after creating

### `talkie data clean`

Remove all Talkie data and start fresh

- `-y, --yes`: skip confirmation
- `--keep-keys`: preserve API keys