Wave CLI

The Wave CLI puts your recordings in the terminal. It's an npm package called @waveai/cli that installs a wave command, so you can list sessions, search them, print a transcript, download audio, or pipe any of it into a script. Every command that returns data takes --json, which makes it easy to compose with other tools.

It's free on every Wave plan and needs Node.js 20 or newer. It runs on macOS, Linux, and Windows.

Install

npm install -g @waveai/cli

To try it without installing anything:

npx @waveai/cli sessions list

Sign in

Run:

wave login

Your browser opens an Authorize Wave CLI page showing the account you're signed in as and what the CLI will be able to do. Click Authorize CLI, and the page confirms with You can close this tab and return to your terminal. The terminal picks up the credential and reports how many sessions you have.

Two other ways to authenticate:

• wave login --token wave_api_... — paste a token you created yourself. Good for CI and headless machines.
• Set a WAVE_API_KEY environment variable. It takes precedence over whatever wave login stored, which makes it easy to run one command as a different account.

wave whoami shows the account, subscription state, and session count. wave logout clears the stored credential from this machine.

To cut off a machine you no longer control, revoke the token named Wave CLI in the Wave web app under the Integrations tab, then Developer API. That kills it everywhere it was used.

The commands

Sessions

• wave sessions list — with --limit, --since (accepts 7d, 2w, 1m), --type, --folder, --tag (repeatable), and --tag-mode.
• wave sessions get <id> — metadata, summary, notes, tags, and phone-call details for one session.
• wave sessions update <id> — set --title, --notes, --tags, --favorite / --no-favorite.
• wave sessions add-folder <session_id> <folder_id> and wave sessions remove-folder — folders are non-exclusive, so adding one doesn't remove another.
• wave sessions action-items get <session_id> and wave sessions action-items update <session_id> — read action items with their version, then write them back from a file or stdin, optionally guarded with --if-match so a concurrent edit in the app is rejected rather than overwritten.
• wave sessions delete <id> — permanent, and it asks for confirmation unless you pass --force.

Content

• wave search "your query" — semantic search, with --limit and --tag filters.
• wave transcript <id> — print a transcript. --format takes text (the default), srt, or segments; --speakers switches to speaker-labeled output, and --json returns the raw response.
• wave media urls <id> — signed audio and video URLs.
• wave media download <id> — saves the audio; add --video for MP4 or --output for a specific path.
• wave bulk [ids...] — export up to 50 sessions at once, with --summary and --transcript.
• wave stats — counts and durations broken down by type and platform.

Folders

• wave folders list — names, ids, and session counts.
• wave folders create "Customer research" --color "#6D28D9" — safe to re-run; a matching name returns the existing folder.

Events and webhooks

• wave events list --ack, wave events ack <cursor>, and wave events tail --interval 3 --ack --json — consume new sessions without hosting a webhook receiver. Wave remembers your position per token.
• wave webhooks list / create / update / test / rotate-secret / delete — manage push delivery, including sending a test event and rotating a signing secret.

Config

wave config get, wave config set <key> <value>, and wave config path manage api_key, api_url, and default_format in your OS config directory. wave config path prints the exact file, which is handy when you're wiping credentials by hand.

A couple of things worth scripting

Back up the last week of recordings, transcript included:

wave sessions list --since 7d --limit 50 --json \
  | jq -r '.sessions[].id' \
  | xargs wave bulk --summary --transcript --json > backup.json

Watch for new sessions and act on each one as it lands:

wave events tail --interval 3 --ack --json

FAQ