Automation & command line

WaveKat Voice ships with a command-line tool so you — or a program you trust, like an AI assistant — can place and manage calls without clicking around the app. It drives the app you already have open; it doesn’t dial on its own.

This is off by default. Turn it on in Settings → Automation. While it’s on, any program on your computer that you run can place calls through your account — which may cost money — so leave it off unless you’re using it.

Turning it on

1. Open Settings → Automation and switch Allow command-line access on.
2. (Optional) Click Install command-line tool to add the wavekat-voice command to your PATH so you can run it from any terminal. On a Mac it may land in a folder that isn’t on your PATH yet — if so, the page shows the exact line to add to your shell profile (with a copy button). If you skip this step entirely, you can still run it from where the app keeps it (the page shows the full path, with a copy button).
3. Keep the app running. The command-line tool talks to the open app; if the app is closed, commands report that it isn’t reachable.

The commands

Commands are grouped by what they act on: call for placing and handling calls, recording for saved recordings, and log for the activity log. Run wavekat-voice call --help (or recording / log) to see every subcommand. Every command that prints data also takes --json for a machine-readable version.

If you didn’t install the tool onto your PATH, replace wavekat-voice with the full path shown on the Automation page — on a Mac that’s inside the app: /Applications/WaveKat Voice.app/Contents/Resources/wavekat-voice.

Placing a call and waiting for the result

call --wait follows the call and exits with a code that says what happened — handy in a script:

wavekat-voice call +14155550123 --wait
echo "result: $?"

Add --launch to call to have it try to open the app first if it isn’t already running (only works if you’d previously turned Automation on).

Finding a call to act on

call list shows what’s happening right now, so you can act on a call you didn’t place yourself — answer an incoming one, or hang up whatever’s connected:

# Hang up every call in progress.
wavekat-voice call list --json | jq -r '.[].id' | while read id; do
  wavekat-voice call hangup "$id"
done

Each entry carries the call’s id, who’s on the other end (party), the direction (inbound / outbound), and whether it’s still ringing or active. Once a call ends it leaves call list and shows up under call history.

Using it with an AI assistant

One-click connect (recommended)

The Settings → Automation page looks for AI assistants you already have installed and offers a Connect button for each — Claude Desktop, Claude Code, Cursor, Codex, Gemini, and Windsurf today. One click sets the assistant up; there’s nothing to copy or paste. Once connected, just ask it to place a call.

A couple of things worth knowing:

• For some assistants you’ll need to fully restart them after connecting (quit and reopen, not just close the window) so they pick up the new calling tools. The app tells you when that’s the case.
• The connection keeps itself current. When WaveKat Voice updates itself in the background, any assistant you’ve connected is quietly kept in sync — you don’t have to reconnect after an update.
• Remove unhooks an assistant again at any time, leaving the rest of its settings untouched.

Why there are two kinds of assistant

Connecting works a little differently depending on how the assistant runs:

• Chat assistants like Claude Desktop can’t see your computer’s files or commands directly, so WaveKat Voice gives them a set of calling tools they can use. This is the only way these assistants can place calls — telling them about the command line alone wouldn’t work, because they can’t reach it.
• Coding assistants like Claude Code, Cursor, or Codex already run commands on your computer, so WaveKat Voice just adds a short note to what they read, telling them the wavekat-voice command is available.

You don’t have to think about which is which — the Connect button picks the right approach for each.

Setting it up by hand

For an assistant that isn’t listed, copy the “Other assistants (manual setup)” snippet from the Automation page into the assistant’s notes or system prompt. Anything that can run a shell can then use the commands above; the --json output is meant for exactly this.

If the assistant speaks the Model Context Protocol, WaveKat Voice also includes a built-in MCP server exposing call control as tools (list_accounts, place_call, list_live_calls, list_history, hangup_call, send_dtmf, mute_call, get_transcript, share_recording, revoke_recording_share). Point your MCP host at:

{
  "mcpServers": {
    "wavekat-voice": {
      "command": "wavekat-voice",
      "args": ["mcp"]
    }
  }
}

(Use the full path to wavekat-voice if you didn’t install it onto your PATH.) With the app running and Automation on, the assistant can place and manage calls directly — no extra setup.

Privacy & safety

• The command-line access is off until you turn it on, and turning it off again immediately revokes it.
• Access is local-only: the tool talks to the app on your own machine, never over the network.
• The same recording and transcription settings apply to calls placed this way as to calls you place by hand.

Stability

While these commands and their --json output may grow new fields over time, the existing fields and the call --wait exit codes are a stable contract — safe to build a script or an assistant integration on.