Your Plaud voice recordings, from the terminal.
plaud is a small, fast Rust CLI for the recordings on your Plaud account —
meetings, interviews, calls, voice memos. List them, read transcripts and AI
notes, pull action items, search across everything, and export to Markdown or
JSON. It's a thin Model Context Protocol
client over Plaud's official MCP server, so it offers the same capabilities
Plaud exposes to AI assistants — but as a Unix tool you can pipe into jq.
$ plaud search "pricing"
=== 2026-06-12 Acme renewal call (a1b2c3…) ===
[14:02] Lee: …so the retainer pricing we discussed was twelve…
(action) Send Acme the updated pricing sheet by Friday
$ plaud export --dir ~/notes/meetings --format md
wrote ~/notes/meetings/2026-06-12-acme-renewal-call.md- macOS (Apple Silicon or Intel) or Windows (x64). Prebuilt binaries are published for both.
- A Plaud account with recordings (you sign in through your browser).
- For the from-source path only: a Rust toolchain (≥ 1.82).
Platform notes:
- Token-file permission hardening (
chmod 0600/0700) is applied on macOS. On Windows the tokens live in your user profile (%USERPROFILE%\.plaud), which is user-scoped by default but not explicitly locked down.- Linux builds and passes tests in CI and will run from source (
cargo install --git …), but isn't a release target and is community-supported.
macOS:
curl -fsSL https://raw.githubusercontent.com/leegonzales/plaud-cli/main/install.sh | shDownloads the prebuilt binary for your Mac from the
latest release,
installs it to ~/.local/bin, and prints PATH guidance. Override the location
with PLAUD_INSTALL_DIR=/usr/local/bin.
Windows (PowerShell):
irm https://raw.githubusercontent.com/leegonzales/plaud-cli/main/install.ps1 | iexDownloads the prebuilt Windows binary and installs it to
%LOCALAPPDATA%\Programs\plaud. Override with $env:PLAUD_INSTALL_DIR.
Both installers fall back to building from source with cargo if no prebuilt
binary matches.
cargo install --git https://github.com/leegonzales/plaud-clicargo binstall --git https://github.com/leegonzales/plaud-cli plaudgit clone https://github.com/leegonzales/plaud-cli
cd plaud-cli
cargo install --path . # -> ~/.cargo/bin/plaud
# or: cargo build --release # -> target/release/plaudThe quick installer puts plaud in ~/.local/bin; cargo install uses
~/.cargo/bin. Make sure the relevant directory is on your PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && exec zshplaud login # opens your browser to sign in (one time)
plaud list # see your recent recordings
plaud sync # pull everything into a local store
plaud search "topic" # full-text search across transcripts and notesplaud whoami # current account
plaud list # recent recordings (table)
plaud list -q standup --from 2026-06-01 --to 2026-06-10
plaud list --page 2 --page-size 50 # page-size >= 10
plaud get <id> # recording summary
plaud note <id> # AI summary / action items / minutes
plaud transcript <id> # transcript: [mm:ss] Speaker: text
plaud download <id> -o talk.mp3 # audio via a 24h presigned URL
plaud logout # forget stored tokensplaud keeps a local store of normalized recordings so search is fast and
offline, and export is cheap. The store lives at ~/.plaud/store/ (override
with PLAUD_STORE).
plaud sync # pull all recordings into the store
plaud sync --since-last # only what's new since the last sync
plaud sync --since 2026-06-01 # only uploads on/after a date
plaud sync --limit 20 # cap work this run (newest first)
plaud search "acme retainer" # full-text over transcripts + notes + titles
plaud search "acme" --context 2 # ± N transcript segments of context
plaud export --dir ./meetings # all synced -> Markdown files
plaud export <id> <id> --dir ./out # specific recordings
plaud export --dir ./out --format json # one JSON per recordingexport --format md writes one YYYY-MM-DD-<slug>.md per recording, with YAML
frontmatter, an action-items checklist, the AI notes, and the transcript —
ready for a Markdown notes app such as Obsidian. Exporting an id that isn't
synced fetches it live and caches it.
plaud list --json | jq '.[].id' # normalized JSON, stable schema
plaud list --ndjson | jq -r .id # one record per line (pipelines)
plaud note <id> --json | jq '.action_items' # action items as a string[]
plaud transcript <id> --ndjson # one segment per line
plaud get <id> --raw # unprocessed Plaud payload
plaud schema # print the stable --json schema--json emits a documented, stable, snake_case schema (see plaud schema).
--ndjson emits one element per line. --raw dumps the unprocessed Plaud
payload. Commands exit non-zero on failure, so they compose safely in scripts.
| What | Where | Notes |
|---|---|---|
| Tokens | ~/.plaud/cli-tokens.json |
Written atomically (mode 0600 on macOS). Removed by plaud logout. |
| Sync store | ~/.plaud/store/ |
Override with PLAUD_STORE. One JSON per recording + a sync cursor. |
| Install dir | ~/.local/bin |
Override the installer with PLAUD_INSTALL_DIR. |
login runs the standard MCP OAuth 2.1 flow against mcp.plaud.ai:
- Discover the protected-resource and authorization-server metadata.
- Dynamically register a public client (PKCE,
token_endpoint_auth_method=none). - Open the browser to authorize; a localhost loopback catches the redirect.
- Exchange the code (PKCE
S256) for access + refresh tokens.
Tokens are cached at ~/.plaud/cli-tokens.json (mode 0600 on macOS; user
profile on Windows) and refreshed automatically on a 401. This file is
separate from the official client's ~/.plaud/tokens-mcp.json, so the two never
collide. logout deletes it.
| Command | MCP tool |
|---|---|
whoami |
get_current_user |
list |
list_files |
get |
get_file |
note |
get_note |
transcript |
get_transcript |
download |
get_file → presigned_url |
transcript and note decode Plaud's nested data_content blocks — the
verbatim transcript and the AI summary / meeting minutes — and fall back to raw
JSON for any block shape they don't recognize.
session expired — run plaud login— your refresh token is no longer valid; runplaud loginagain.plaud: command not found— the install dir isn't on yourPATH. See PATH.downloadsays no audio — Plaud doesn't keep apresigned_urlfor every recording (short clips especially). That's expected, not a bug.- Empty transcript / notes — not every recording is transcribed on Plaud's
side; older clips may have none.
transcript/notereport this clearly. page_size: Input should be greater than or equal to 10— Plaud requires--page-size≥ 10.search/exportsay the store is empty — runplaud syncfirst; they read the local store.
skill/use-plaud/SKILL.md is a ready-made
Claude Code skill that teaches an AI agent how
to drive this CLI — the commands, the stable --json/--ndjson contract, the
sync→search→export flow, and common recipes. Drop it into your agent's skills
directory (e.g. ~/.claude/skills/use-plaud/) to let an assistant work your
recordings for you. It's generic — no personal data, no assumptions about your
setup.
cargo test # unit tests
cargo fmt --all -- --check # formatting
cargo clippy --all-targets -- -D warnings # lints (zero-warning bar)
cargo build --releaseCI runs all of the above on every push and PR; tagged releases build macOS binaries automatically. The codebase is small and organized one concern per module:
oauth.rs— discovery, DCR, PKCE, loopback redirect, token + refreshmcp.rs— Streamable-HTTP MCP client (initialize, session id,tools/call)model.rs— normalize Plaud's nested payloads into one stableRecordstore.rs— local sync store (records + cursor)commands.rs— one handler per subcommandoutput.rs— human-readable rendering (table, transcript, notes)config.rs— token storage
Contributions welcome — please keep cargo fmt/clippy/test green.
This is an unofficial project, not affiliated with, endorsed by, or
supported by Plaud. It talks to the same MCP endpoint Plaud documents for AI
assistants (https://mcp.plaud.ai/mcp), using your own account via the
standard OAuth flow — it stores no credentials beyond the tokens that flow
returns, kept locally at ~/.plaud/cli-tokens.json (mode 0600). Use it with
your own recordings and at your own risk. Endpoint or payload changes on
Plaud's side may break it.
MIT © Lee Gonzales