Automate · @waveai/cli

Your meeting library, one command away.

Search transcripts, organize sessions, stream events, and build reliable exports without leaving the terminal.

Install the CLI View on npm

Node 20+macOS, Linux, WindowsHuman + JSON output

~/projects

❯ wave search "launch risks"

0.91 Product review

"The migration date is the main risk…"

0.84 Launch retro

"We still need an owner for QA…"

❯ wave events tail --ack --json

{"event":"session.completed","seq":148}

waiting for events

Install

npm install -g @waveai/cli

Install

Start globally, or keep it disposable.

The package exposes the wave binary and requires Node.js 20 or newer.

Global install

npm install -g @waveai/cli

Run with npx

npx @waveai/cli sessions list

Authenticate

Use the browser once, or bring your own token.

Browser login is the quickest path for a person. Environment variables and explicit tokens are better for automation.

Browser OAuth

Opens Wave in your browser, verifies the account, and saves the returned API token in the operating system config directory.

wave login

Token or environment

Mint a scoped token in Wave settings, then paste it or set WAVE_API_KEY.

wave login --token wave_api_...

WAVE_API_KEY takes precedence over stored config. Keep it out of shell history, logs, and source control.

Command reference

A complete toolbelt, organized by job.

Every command maps closely to the Wave API. Add --json wherever machine-readable output is supported.

Sessions

Read, organize, update, and remove sessions.

wave sessions list

List with pagination plus type, date, folder, and repeatable tag filters.

wave sessions list --folder work --since 7d --tag roadmap --json

wave sessions get <id>

Show metadata, summary, notes, tags, and phone-call details for one session.

wave sessions update <id>

Patch title, notes, tags, or favorite state with sessions:write.

wave sessions update sess_01J... --tags work,roadmap --favorite

wave sessions add-folder <session_id> <folder_id>

Add one folder membership without replacing any existing folder.

wave sessions remove-folder <session_id> <folder_id>

Remove one folder membership while keeping the session intact.

wave sessions action-items get <session_id>

Read structured action items and the version used for safe write-back.

wave sessions action-items update <session_id>

Replace action items from stdin or a JSON file, optionally guarded by --if-match.

wave sessions action-items update sess_01J... --from-file actions.json --if-match 3

wave sessions delete <id>Destructive

Permanently delete a session after confirmation. --force skips the prompt.

Search & content

Find, format, download, and export session content.

wave search <query>

Semantic search with result limits and repeatable any/all tag filters.

wave search "retail media strategy" --tag roadmap

wave transcript <id>

Print a transcript as plain text, SRT, speaker segments, or raw JSON.

wave transcript sess_01J... --format srt

wave media urls <id>

Return signed audio and video URLs. wave media <id> is a shortcut.

wave media download <id>

Download audio, or pass --video for MP4 and --output for a custom path.

wave media download sess_01J... --output interview.m4a

wave stats

Summarize session count and duration by type and platform for a date range.

wave bulk [ids...]

Export up to 50 sessions from arguments or --file, with optional summaries and transcripts.

wave bulk --file ids.txt --summary --transcript --json

Folders

Create a durable structure around your session library.

wave folders list

List folder IDs, names, colors, and session counts for use in other commands.

wave folders create <name>

Create a folder idempotently, with an optional hexadecimal color.

wave folders create "Customer research" --color "#6D28D9"

Event feed

Consume per-token events without hosting a receiver.

wave events list

Pull from the server-tracked cursor; pass --ack to advance it after reading.

wave events list --limit 100 --ack --json

wave events ack <cursor>

Advance the monotonic cursor explicitly after successful processing.

wave events tail

Poll continuously and print events as they arrive; tune --interval and optionally --ack.

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

Webhooks

Operate push delivery and signing secrets end to end.

wave webhooks list

List endpoints, subscribed events, status, and last delivery time.

wave webhooks create

wave webhooks create --url https://example.com/wave --events session.completed,session.updated

wave webhooks update <id>

Change the URL, event set, or active state for an existing endpoint.

wave webhooks test <id>

Send a test event and report whether delivery succeeded.

wave webhooks rotate-secret <id>

Issue a new signing secret and display it once for secure storage.

wave webhooks delete <id>Destructive

Delete an endpoint after confirmation.

Identity & config

Control credentials, output, and alternate API targets.

wave login / logout / whoami

Authenticate in a browser or with --token, clear credentials, and inspect the current account.

wave config get [key]

Read one setting or the masked configuration currently in effect.

wave config set <key> <value>

Set api_key, api_url, or default_format in the OS configuration directory.

wave config path

Print the exact configuration-file location.

Workflows

Compose small commands into useful systems.

The CLI stays close to standard input, standard output, and exit codes, so familiar shell tools do the orchestration.

backup-recent-sessions.sh

# Collect the 50 newest session IDs
wave sessions list --limit 50 --json \
  | jq -r '.sessions[].id' > session-ids.txt

# Export metadata, summaries, and transcripts
wave bulk --file session-ids.txt \
  --summary --transcript --json > wave-backup.json

jq '.sessions | length' wave-backup.json

action-items.sh

# Read the current version first
VERSION=$(wave sessions action-items get "$SESSION_ID" --json \
  | jq -r '.version')

# Safely replace the list; fail if someone edited it meanwhile
wave sessions action-items update "$SESSION_ID" \
  --from-file actions.json --source agent --if-match "$VERSION" --json

Automation

Designed to behave well in scripts.

Predictable output and explicit state make the CLI suitable for local tooling, cron jobs, and lightweight agents.

JSON output

Use --json and pipe clean data into jq, files, or another process.

Clean streams

Normal output goes to stdout; failures go to stderr with a non-zero exit.

Real files

Export structured archives and download media directly to a chosen path.

Need the raw contract?

Go from command to endpoint.

Inspect schemas, parameters, auth requirements, and live request examples in the interactive API reference.

Open API reference