wavekat

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. It can also run with no app at all, on a server or any Mac or Linux computer — see Without the app.

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.

Installed from Flathub? There is no step 2 — the Automation page shows the command to use instead, and you run it through Flatpak:

flatpak run --command=wavekat-voice com.wavekat.Voice status

Everything below works the same way; just put that in front of each command in place of wavekat-voice.

One difference worth knowing: when you save a recording, put it in your Downloads folder — --out ~/Downloads/call.wav. That’s the one place a Flathub install is allowed to write, so a path anywhere else is refused. (If your desktop is in another language the folder has a different name; xdg-user-dir DOWNLOAD prints the right path.)

Keep running in the background

On a Mac or on Linux, turn on Settings → Automation → Keep running in the background and WaveKat Voice keeps answering calls — with your call flow, and for programs on this computer — after you close the app. It also starts when you log in. While it’s on, command-line access stays on, since it’s running for exactly that. Switching it on or off ends a call in progress.

It’s the same as wavekat-voice service install below, so the switch and the command line always agree. Not available in the App Store version, the Snap or Flathub packages, or on Windows.

Without the app

The calling engine inside the app can be installed and run on its own, on a Mac or on Linux, with no window: on a server, on a computer an AI assistant works from, or on a Mac where WaveKat Voice came from the App Store (that version’s command-line tool only works inside the app). The easiest way is the WaveKat command-line tool, wk:

curl -fsSL https://dl.wavekat.com/wk/install.sh | sh
wk voice install      # install the engine
wk voice service install
wk voice setup        # agree to the terms, add your phone line
wk voice call +14155550123 --wait

wk voice … and wavekat-voice … are the same commands. service install keeps the engine running in the background and starts it again when you log in. On a computer with no service manager, such as most containers, use wk voice serve --background instead: it keeps running after you close the terminal, but you start it again after a restart. setup walks you through the rest: the terms, your phone line (it tests the connection first and picks the setting that works), and, if you want, your WaveKat account. Your line’s password is saved where the app saves it — in your login keychain on a Mac, in a file only you can read on Linux — so a line you add here shows up in the app and the other way round.

Starting the engine over SSH on a Mac with no one logged in at the screen? The login keychain is locked then, so the engine stops with an error instead of running without your passwords. Log in at the Mac, or run security unlock-keychain first. Or set WAVEKAT_SECRET_STORE=file for that engine: it then keeps passwords in a private file instead, and you add your lines to it again, since it can’t see the ones in the keychain.

If the app is already installed, wk voice install uses the app’s engine instead of downloading another, and the app keeps it up to date. If you install the app later, it uses the engine that’s already running, with the same lines and call history. On Linux the engine needs a recent system (Ubuntu 24.04 or newer, or the same generation of another distribution). The Windows version isn’t available yet.

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. Two more stand alone: pause and resume control whether your lines take calls. 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.

CommandWhat it does
wavekat-voice statusIs the app running? Lists your accounts and whether each is connected, and whether you’re currently taking calls.
wavekat-voice accountsList your SIP accounts and their connection state.
wavekat-voice pauseStop taking calls on every line — callers reach your call flow or voicemail. Add --line <account-id> for one line, --for <minutes> to resume automatically, --offline to sign the line out instead.
wavekat-voice resumeTake calls again (every line, or --line <account-id>).
wavekat-voice call <to>Place a call. <to> is a phone number (+14155550123 or local digits) or a SIP address (sip:alice@example.com). Prints the new call’s id.
wavekat-voice call <to> --waitPlace a call and stay attached until it ends; the command’s exit code tells you how it went (see below).
wavekat-voice call listList the calls happening right now (ringing or connected) — the way to find a call’s id to answer, hang up, or send tones to.
wavekat-voice call historyList finished calls, most recent first. Add --limit and --before to page through older calls.
wavekat-voice call <to> --say "<text>"An automated call: when the other side answers, a voice says the text, then hangs up. Add --voice <id> to pick the voice. Works without signing in: your computer’s voice or your own speech service says the text (see Automated calls).
wavekat-voice call <to> --play <file>An automated call that plays an audio file (WAV, MP3, OGG/Opus, FLAC or M4A — up to 2 minutes and 20 MB), then hangs up.
wavekat-voice call <to> --flow-file <flow.yaml>An automated call run by a call flow you wrote — greetings, a keypad menu, taking a reply. See Automated calls.
wavekat-voice call <to> --flow <name>An automated call run by a ready-made flow you installed (see Ready-made flows), or by a flow you published on your WaveKat account, by its id or its name.
wavekat-voice call <to> --flow <id or name> --var <name>=<value>The same, with your own text for the flow’s details, such as a name or a question, in place of the ones saved in the flow. Repeat --var for each one, or use --vars-file <file.json>.
wavekat-voice call <to> --say "…" --checkPrepare an automated call without placing it: checks the flow, makes its voice prompts, and reports how many text-to-speech characters that used. Works with --play, --flow-file and --flow too.
wavekat-voice call <to> --say "…" --tts <source>Choose who says the text: wavekat, openai, elevenlabs, command, reo or system. Add --tts-command "<command>" to use your own speech program.
wavekat-voice call <to> --say "…" --accept-termsAgree to the terms of service as part of placing the call, if you haven’t yet.
wavekat-voice voicesList the voices automated calls can speak in, for --voice.
wavekat-voice call answer <id>Answer a ringing call.
wavekat-voice call reject <id>Decline a ringing call.
wavekat-voice call hangup <id>End a call.
wavekat-voice call mute <id>Mute your microphone on a live call. Add --off to unmute.
wavekat-voice call hold <id>Put a call on hold. Add --off to take it off hold.
wavekat-voice call transfer <id> <to>Hand a call over to another number or SIP address.
wavekat-voice call transfer <id> --with <other-id>Transfer after talking first: put the call on hold, call the new person with wavekat-voice call <to>, then join the two calls and drop off.
wavekat-voice call dtmf <id> <digits>Send touch-tones, e.g. 1234#, to navigate a phone menu.
wavekat-voice call transcript <id>Print a call’s transcript (if transcription was on). Add --follow to print it live while the call goes on.
wavekat-voice call show <id>One call’s details: who, when, how it ended, whether it was recorded.
wavekat-voice call delete <id>Delete one call from your history, with its recording and transcript.
wavekat-voice call heard <id>Mark a voicemail message as heard.
wavekat-voice call clear-historyErase all finished-call history and the recording files on disk. Accounts and sign-in are kept. Cannot be undone.
wavekat-voice recording download <id> --out call.wavSave a call’s recording to a file.
wavekat-voice recording delete <id>Delete a single call’s recording.
wavekat-voice recording summaryHow many recordings you’ve saved and how much space they use.
wavekat-voice recording clearDelete every saved recording (the call history is kept).
wavekat-voice recording share <id> --visibility restricted --invite you@example.comShare a recording by link with specific signed-in people.
wavekat-voice recording share <id> --visibility public --yesShare a recording with anyone who has the link (--yes is required — public means no sign-in).
wavekat-voice recording share <id> --visibility … --identity masked --transcript hide --audio show --download deny --plays bothChoose what a viewer sees. --identity hidden|masked|shown, --transcript show|hide, --audio show|hide, --download allow|deny, --plays both|you|them (download and plays apply only when audio is shown; --plays picks which side(s) play by default — the viewer can still un-mute the other). Omit them for the privacy-forward defaults: identity masked, transcript hidden, audio shown, download off, both sides play.
wavekat-voice recording unshare <id>Stop sharing a recording (the link stops working).
wavekat-voice log listList recent activity. Add --account <id> to filter.
wavekat-voice log clearClear the activity log (optionally --account <id>).
wavekat-voice transcriptionIs live transcription on, and which model is it using? Lists the models and which are downloaded.
wavekat-voice transcription download [model]Download a transcription model (the selected one if you don’t name one) and wait until it’s ready.
wavekat-voice transcription on / offTurn live transcription on or off for calls from now on. on --model <model> switches models too; the model has to be downloaded first.
wavekat-voice transcription model <model>Switch models: bilingual_zh_en, en, zh or paraformer_zh_en.
wavekat-voice settingsShow your settings: recording, cloud sync, error reports, install count, keypad sounds, microphone and speaker.
wavekat-voice settings <name> on|offChange one: recording, cloud-sync, error-reports, install-count or keypad-sounds.
wavekat-voice settings devicesList your microphones and speakers. Pick one with settings microphone <id> or settings speaker <id> (default follows your computer).
wavekat-voice flowsYour call flows, the ready-made flows you installed (each with where it came from), and which line each one answers.
wavekat-voice flows show <flow>One flow: whether it’s ready, and its steps. Takes a flow’s id or an installed flow’s name.
wavekat-voice flows install <name>Install a ready-made flow from WaveKat’s own collection, or <name>@<collection> from one you added. It says which phone numbers the flow can pass a call to, if any.
wavekat-voice flows uninstall <name>Remove an installed flow. flows update fetches the latest version of every installed flow (or flows update <name> for one).
wavekat-voice flows marketplace add <owner/repo>Add another collection of ready-made flows: a GitHub project, or an https:// link to its marketplace.json. flows marketplace list shows them; flows marketplace remove <name> removes one and the flows installed from it.
wavekat-voice flows use <flow-id> --line <account-id>Answer a line’s calls with a flow. flows off --line <account-id> lets the line ring normally again.
wavekat-voice flows refreshFetch your latest flows and contacts from your WaveKat account now.
wavekat-voice contactsThe names your WaveKat account gives callers. --search <text> finds one; contacts refresh fetches the latest.
wavekat-voice eventsWatch calls and account changes live. --json prints one event per line.
wavekat-voice setupSet up an engine running without the app, step by step: start it, agree to the terms, add a phone line. Safe to run again. Without a terminal, or with --json, it only lists what’s left and the command for each step.
wavekat-voice accounts addAdd a phone line. Asks for the username, domain and password (hidden), tests the connection, and saves the setting that works. A mistyped password can be typed again. Scripts pass --user and --domain, and the password with --password-stdin, --password-file <path>, --password-command '<cmd>' (for a password manager, like op read …) or the WAVEKAT_SIP_PASSWORD environment variable.
wavekat-voice accounts remove <id>Remove a phone line.
wavekat-voice accounts show <id>One line’s settings and whether it’s connected.
wavekat-voice accounts edit <id>Change a line: --name, --user, --domain, --server, --port, --transport, --auth-user, --password (asks, hidden), --password-stdin, --password-file or --password-command, --line on|off, --recording-notice on|off, --backup off|settings. Only what you pass changes.
wavekat-voice accounts sign-in [id]Connect a line now (every line if you leave out the id).
wavekat-voice accounts diagnostics <id>Connection details for a line, for troubleshooting or to send to support.
wavekat-voice termsShow the terms of service; --accept agrees to them. Signing in to WaveKat agrees for you when your account already agreed to these terms or a later version. Automated calls need it; ordinary calls don’t.
wavekat-voice login / logoutSign in to (or out of) your WaveKat account, through a link you open in a browser. Over SSH (or with --no-browser), open the link on any device and paste the code it shows. wk voice login signs in with your wk sign-in instead, with no browser. Lines and calls from before you signed in can be added to your account: it asks, or --claim adds them.
wavekat-voice service installRun the engine in the background without the app, and start it when you log in. Also uninstall, start, stop, restart, status. Mac and Linux with systemd.
wavekat-voice serve --backgroundStart the engine in the background where there’s no service manager, such as a container. Start it again after a restart; stop stops it.
wavekat-voice stopStop the engine running without the app, whether it runs in the background or you started it with wavekat-voice serve. Refuses while a call is in progress unless you add --force. To stop the app’s engine, quit the app.

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. On a Flathub install, replace it with flatpak run --command=wavekat-voice com.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:

Exit codeMeaning
0Answered, then ended normally — or the call was handed over to someone else (see below).
1Couldn’t place the call (app not running, bad number, …).
2Busy, or the other side declined.
3The call failed, or a connected call dropped.
4No answer (cancelled before pickup, or missed).
wavekat-voice call +14155550123 --wait
echo "result: $?"

Calling without the app

You don’t need a saved phone line or the app open to place a call. If you have a SIP account, give it in environment variables and call uses it for that call only. Nothing is saved or synced:

export WK_SIP_URI="sip:alice@example.com"
export WK_SIP_PASSWORD_FILE=~/.secrets/sip-password
wavekat-voice call +14155550123 --say "Your table is ready." --wait

WK_SIP_URI is the line’s address; WK_SIP_AUTH_USER and WK_SIP_SERVER are optional. The password comes from the first of WK_SIP_PASSWORD_COMMAND (a command that prints it), WK_SIP_PASSWORD_FILE (a file holding it) or WK_SIP_PASSWORD. Prefer the command or the file: they keep the password out of your shell history. --account <id> picks a saved line instead and the variables are ignored.

If nothing is running, call starts a short-lived engine just for that call and stop it afterwards. Only one such call runs at a time on a computer; a second one tells you to wait for the first. A call that hands the person over to someone can leave that engine running for up to 15 seconds more. If the app is open with Automation turned off, nothing is started; turn Automation on. Even without --wait, a call on a short-lived engine returns only when the call ends.

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).

Automated calls

An automated call is one where a call flow does the talking: nobody needs to be at the computer, and no microphone or speaker is used — so it works on a server or over SSH too. Pick one of --say, --play, --flow-file or --flow:

wavekat-voice call +14155550123 --say "Your table is ready. See you soon." --wait
wavekat-voice call +14155550123 --play reminder.mp3
wavekat-voice call +14155550123 --flow-file confirm.yaml --wait --json

You don’t need a WaveKat account for these. When you’re not signed in, your computer says the text: with an OpenAI or ElevenLabs key from your environment (OPENAI_API_KEY or ELEVENLABS_API_KEY), with a speech program of your own (--tts-command "<command>" or WK_TTS_COMMAND), with reo, or with the voice built into your computer (say on a Mac, espeak-ng on Linux, the built-in voice on Windows), in that order. WaveKat’s own voice is used when you’re signed in.

reo is WaveKat’s free voice that runs on your computer and sounds far more natural than the built-in one, which is robotic. It works on Macs with Apple silicon and on Linux. Install it with:

curl -fsSL https://reo.wavekat.com/install.sh | sh

The first call after installing takes a little longer while reo downloads its voice, once.

--tts wavekat|openai|elevenlabs|command|reo|system picks one yourself; if the one you pick can’t be used, the call isn’t placed. With --json or --check, the result says which one was used, as speech: { source, voice }. A call that only plays a recording (--play, or a flow made of audio files) needs no voice at all. Your key goes only to its own provider.

--flow takes the name of a ready-made flow you installed, or a flow’s id or name from your WaveKat account (capitals and extra spaces don’t matter). If more than one flow has that name, the error lists each as name@source, such as ask@wavekat or ask@account: pass that instead.

Everything is checked before the phone rings: the flow, its audio files and its voice prompts. If anything is wrong — a step an outgoing call can’t use, a file that isn’t audio, text that’s too long, no text-to-speech allowance left — you get a plain error and exit code 1, and no call is placed. --check runs those same checks without calling; the prompts it makes are kept, so the real call right after costs nothing more.

A flow file is the same YAML as a published flow. An outgoing call can use greeting, menu, message, hangup and hours steps (not book, which needs a caller to book), and no loop that could repeat forever. A flow that starts with schema_version: 3 can also hand the person you called to someone (see below). Each prompt can be text, a local audio file next to the flow ({ audio: ./hello.wav }), or a clip from your WaveKat prompt library ({ audio: vprompt_… }):

schema_version: 1
id: confirm
name: Appointment confirmation
entry: ask
nodes:
  ask:
    kind: menu
    prompt: "Hi, this is Riverside Dental confirming tomorrow at 10. Press 1 to confirm, or 2 to cancel."
    options: { "1": Confirm, "2": Cancel }
    exits: { "1": thanks, "2": cancelled, no_input: thanks, invalid: thanks }
  thanks: { kind: hangup, prompt: "Thank you, goodbye." }
  cancelled: { kind: hangup, prompt: "Your appointment is cancelled. Goodbye." }

With --wait --json, an automated call prints one line per step of the flow between its call-state lines — {"type":"flow_started",…}, then {"type":"flow_step","node":"ask","kind":"menu","digit":"1","exit":"1"} for each step, then {"type":"flow_finished","completed":true,"path":[…],"digits":"1",…}. The exit codes are the same as for any call. Afterwards, call history --json marks the call "automated": true with a flow object saying which flow ran, the steps it took, the keys pressed and whether it played to the end.

Details for each call

A published flow can have details that change from call to call, such as the name of the person you’re calling or a question to ask. Give your own with --var, once per detail, or read them all from a JSON file of text values with --vars-file; --var wins over the file. Both work the same with a flow you wrote yourself (--flow-file). Anything you leave out keeps the flow’s saved text:

wavekat-voice call +14155550123 --flow "Appointment question" \
  --var name=Jane --var question="Is 5pm OK?" --wait --json

Your text is spoken when the call is placed, so it counts toward your account’s text-to-speech allowance (text you’ve used before is remembered and costs nothing again). --check shows what it would use. The call’s history keeps which flow ran and the option the person picked (its text), but not the question you passed.

When the person called pressed a key, the flow_finished line carries choices, a list of {"node","digit","label","loops"} in the order they chose. A flow_step line carries the option’s label too. The answer is the last choice whose loops is false; a choice with loops: true, such as pressing 9 to hear the question again, is not an answer, and an empty list means they didn’t answer.

Handing the call to a person

A schema_version: 3 flow can pass the person you called to you or a colleague, usually when they ask for it by pressing a key:

  • A ring step (it needs a timeout_secs, how long to ring) rings the WaveKat Voice app on the same computer. If you answer on screen, you’re talking to them. If the app isn’t open, the flow goes straight to the step’s no_answer exit.
  • A transfer step with a whisper calls target (a phone number) first. The person who answers hears your whisper prompt and then “Press 1 to take the call.” and has about 10 seconds to press a key. Only if they press 1 is the person you called connected. A wrong key or silence replays the message once; after two tries without 1, or if they hang up, the flow takes the step’s no_answer exit and the person you called hears your fallback instead. timeout_secs (5 to 120, default 25) sets how long to let target ring. A transfer with no whisper is refused on automated calls.

Handing a call to a phone number depends on your phone provider supporting call transfer; if it doesn’t, the hand-off ends as failed and the flow takes no_answer. Here’s an interview reminder that offers to connect the candidate to HR:

schema_version: 3
id: interview-reminder
name: Interview reminder
entry: ask
nodes:
  ask:
    kind: menu
    prompt: "Hi Jane, this is Acme HR about your interview tomorrow at 10am. Press 1 to confirm, or 2 to talk to someone."
    options: { "1": Confirm, "2": Talk to HR }
    exits: { "1": thanks, "2": to_hr, no_input: later, invalid: later }
  to_hr:
    kind: transfer
    target: "+64211234567"
    whisper: "Interview reminder for Jane Lee. She asked to talk."
    timeout_secs: 25
    exits: { no_answer: callback }
  thanks: { kind: hangup, prompt: "Thanks, see you tomorrow." }
  callback: { kind: hangup, prompt: "Sorry, nobody is free right now. HR will call you back today." }
  later: { kind: hangup, prompt: "We'll try you again later. Goodbye." }

When a hand-off ran, the flow_finished line (and the flow object in call history --json) carries a handoff field: {"to":"phone","target":"+64211234567","outcome":"answered"}. to is phone or app; outcome is answered, no_answer, failed, or caller_hung_up (the person you called left while it was still being tried). The field is left out when no hand-off ran. An answered hand-off counts as completed, and call --wait exits 0 as soon as it is answered, without waiting for the conversation to end. A call that was handed over this way also exits 0.

The rules for automated calls:

  • You need to have agreed to the terms (wavekat-voice terms, or add --accept-terms to the call). Signing in (wavekat-voice login) is optional.
  • When you’re signed in, text prompts are spoken by WaveKat’s text-to-speech and count toward your account’s allowance, including any text you pass with --var. Signed out, your computer or your own speech service says them, and WaveKat’s allowance isn’t used.
  • One automated call at a time per line, and at most 20 an hour: per account when you’re signed in, per computer when you’re not. The limit is set on the engine; the command can’t raise it.
  • The call always shows your line’s own number.
  • The terms of service apply: no automated calls or recorded messages to people who haven’t asked to hear from you.
  • Each call is capped at 10 minutes once answered.

Asking a question

To ask someone a question and hear which key they press, run a flow with a keypad menu and give the question with --var. Save this as question.yaml:

schema_version: 4
name: Ask a question
entry: ask
variables:
  intro:    { description: Who is asking, default: "Claude has a question.", max_len: 120 }
  question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 }
  option1:  { description: Answer for key 1, default: "Yes", max_len: 80 }
  option2:  { description: Answer for key 2, default: "No", max_len: 80 }
nodes:
  ask:
    kind: menu
    prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}. Press 9 to hear this again."
    options: { "1": "{{option1}}", "2": "{{option2}}", "9": Repeat }
    retries: 1
    timeout_secs: 8
    exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye }
  thanks: { kind: hangup, prompt: "Got it, thanks. Goodbye." }
  bye: { kind: hangup, prompt: "No answer recorded. Goodbye." }
wavekat-voice call +14155550123 --flow-file question.yaml \
  --var question="Ship it today?" --var option2="No, wait" --wait --json

Near the end, just before the call’s ended line, comes {"type":"flow_finished",…,"choices":[…]}. Look for that line by its type rather than taking the last line. A flow_finished line means the call was picked up, and choices lists the keys pressed with their answers: the answer is the last choice whose loops is false (9 = repeat isn’t an answer). The ready-made ask flow does the same without a file of your own (see Ready-made flows).

Picked up with no valid key pressed is most often voicemail, not a person: most mobile phones send a declined or unanswered call to voicemail, and voicemail picks up. Treat it like no answer: try again later, or send a message instead.

Ready-made flows

Ready-made flows are call flows someone else wrote, ready to use with call --flow. WaveKat’s own collection includes ask (one question, answered with a key) and notify (a message said twice):

wavekat-voice flows install ask
wavekat-voice call +14155550123 --flow ask \
  --var question="Ship it today?" --var option1="Yes" --var option2="No, wait" \
  --wait --json

ask takes intro (who is asking), question, and option1 to option4 (key 1 to key 4; 9 repeats the question). If you call --flow ask before installing it, it’s installed from WaveKat’s collection first, and a note says so. Flows from collections you added yourself are never installed without flows install.

An installed flow is a file on your computer: it works without signing in, and keeps working offline. Each one is checked when it’s installed, the same way as --flow-file, and flows install tells you every phone number the flow can pass a call to. Read the result as in Asking a question: a flow_finished line means the call was picked up, and no valid key pressed is most often voicemail.

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

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, check_flow, list_voices, list_live_calls, list_history, hangup_call, send_dtmf, mute_call, get_transcript, share_recording, revoke_recording_share, get_availability, pause_calls, resume_calls). place_call places an automated call when given one of say, audio, flow_yaml, flow_id or flow_name, plus optional vars (see Details for each call), with the same checks and rules as the command line. 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.)

Installed from Flathub? The MCP host starts the program itself, so it needs flatpak as the command and the rest as arguments — a single string with spaces in command will not start:

{
  "mcpServers": {
    "wavekat-voice": {
      "command": "flatpak",
      "args": ["run", "--command=wavekat-voice", "com.wavekat.Voice", "mcp"]
    }
  }
}

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 one exception is fetching ready-made flows (flows install, flows update, flows marketplace add, or call --flow installing one for you), which downloads the flow files and nothing else.
  • The same recording and transcription settings apply to calls placed this way as to calls you place by hand.
  • Automated calls are listed in History as “Automated”, with the flow that ran. A flow file an assistant sends is kept with the call, so you can always see what was said on your line.

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.