This page covers the commands provided by the
List contacts, sorted by favorites, presence, then name.
Emit the complete contact list as JSON Lines whenever it changes. The first line is the initial snapshot. This command does not accept the list filters.
Show one contact’s ID, name, email, presence, kind, and favorite state.
Favorite or unfavorite a contact.
Remove a contact.
Invite someone to Tuple by email.
List ongoing calls.
Show the active call, or select an active or retained call by exact ID. An unambiguous retained-call ID prefix also works.If you omit the selector while outside a call, the command returns
Set a call’s title or summary. You must pass
Start a 1:1 call with a contact or one of your connected machines. Get machine IDs from
Join a contact’s call or a room slug or URL. Tuple tries the argument as a contact first. Pass
Add or remove someone from a call. Both commands accept
Leave a call.
Mute or unmute your microphone.
Play
Manage Tuple rooms. Existing-room commands accept an exact slug, such as
List your personal and team rooms. Occupied rooms come first, followed by favorites, then name.
Emit the complete filtered room list as JSON Lines when the result changes. It supports
Show one room by exact slug or URL.
Join a room without resolving the argument as a contact. Pass
Favorite or unfavorite a room.
Create a team room.
List your other signed-in, connected machines. Each result contains its machine ID, platform, device name when available, and current call ID when that machine is in a call. Use a machine ID with
Save the shared screen as a JPEG with visible annotations composited in.
Control call capture, read its records, and find or export stored calls. The app owns the local archive. Use the CLI instead of reading its database directly.Capture records have three categories:
Start or stop capture.
Print a finite snapshot, then exit. Omit the selector for the active call, use
Follow records continuously. Without a call ID, it stays subscribed across calls. When pinned to a call or recording session, it ends with that scope.
Return one batch and exit. The first read without
List stored calls newest first. Results include call metadata, a segment count, and resolved participants.
Search stored speech and shared app names, window titles, and URLs. Results are newest first.
Write selected records from one or more calls to one artifact file. The destination is replaced only after the complete artifact is ready. If no calls match, the command fails and leaves an existing destination untouched. On POSIX systems, the file mode is
Permanently delete one stored call’s conversation, events, content, and retained media. This cannot be undone.
The
Post a notice without waiting for a response.
Post a decision card and wait.
Return bounded notification containers with their current state, response, timestamps, and lifecycle.
Follow notification lifecycle events. With
Withdraw a card you posted. Only the user can accept or reject it.
Print the signed-in user’s email in text output.
Print a bounded orientation summary. It contains the active call, current user, contact and room counts, pending-invite count, connection state, platform, app version, and available update. Its
Emit a complete bounded summary whenever it changes. With
Read operating guidance embedded in this CLI build. Run
Launch the configured AI agent with current-call context and embedded operating instructions. With
Print the same instructions without launching an agent. It accepts
Configure the default agent and its launch settings. This command requires a terminal.
Run the Tuple MCP server over stdin and stdout. See the MCP server page.
Register the server with detected supported agents, or name one or more of
tuple CLI. For installation instructions, see the Tuple CLI overview.Global flags
Errors go to stderr. With
--format json, errors are JSON objects with an error field and may include error_code and kind. Use JSON for a stable machine-readable contract. Text output is for people.Person arguments
Commands with a<person> argument search contact names and email addresses. One match selects that contact. No matches return an error. Multiple matches return an error and list the candidates.tuple contacts
contacts list [flags]
List contacts, sorted by favorites, presence, then name.Filters combine with AND. An empty result succeeds and returns an empty list.
contacts follow
Emit the complete contact list as JSON Lines whenever it changes. The first line is the initial snapshot. This command does not accept the list filters.contacts show <person>
Show one contact’s ID, name, email, presence, kind, and favorite state.contacts favorite <person> / contacts unfavorite <person>
Favorite or unfavorite a contact.contacts remove <person>
Remove a contact.contacts invite <email>
Invite someone to Tuple by email.tuple call
call list [flags]
List ongoing calls.call show [call] [--only <field>]
Show the active call, or select an active or retained call by exact ID. An unambiguous retained-call ID prefix also works.--only prints one field without a label. Valid fields are id, state, participants, title, summary, started_at, and ended_at.not in a call and exits nonzero.call edit [call]
Set a call’s title or summary. You must pass --title, --summary, or both. An empty value clears that field.call start <person-or-machine-id>
Start a 1:1 call with a contact or one of your connected machines. Get machine IDs from machines list.--wait waits for the connection. --timeout controls how long it waits and defaults to 30s. A wait exits 0 when connected, 2 if the call ends first, and 3 on timeout.call join <person-or-url>
Join a contact’s call or a room slug or URL. Tuple tries the argument as a contact first. Pass --switch to leave your current call before joining.call participants add <person> / call participants remove <person>
Add or remove someone from a call. Both commands accept --call, which defaults to current. add also accepts the same --wait and --timeout behavior as call start.call leave
Leave a call. --call defaults to current.call mute / call unmute
Mute or unmute your microphone. --call defaults to current.call react <sound>
Play airhorn, trombone, or flute for everyone on the call. --call defaults to current.tuple rooms
Manage Tuple rooms. Existing-room commands accept an exact slug, such as acme/general, or a full room URL.rooms list [flags]
List your personal and team rooms. Occupied rooms come first, followed by favorites, then name.rooms follow [flags]
Emit the complete filtered room list as JSON Lines when the result changes. It supports --kind, --occupied, --favorited, and --limit.rooms show <slug-or-url>
Show one room by exact slug or URL.rooms join <slug-or-url>
Join a room without resolving the argument as a contact. Pass --switch to leave your current call first.rooms favorite <slug-or-url> / rooms unfavorite <slug-or-url>
Favorite or unfavorite a room.rooms create <name>
Create a team room.tuple machines
machines list
List your other signed-in, connected machines. Each result contains its machine ID, platform, device name when available, and current call ID when that machine is in a call. Use a machine ID with tuple call start to call that device.tuple screen
Save the shared screen as a JPEG with visible annotations composited in.For stored frames, read stderr for timing and annotation caveats.
tuple capture
Control call capture, read its records, and find or export stored calls. The app owns the local archive. Use the CLI instead of reading its database directly.Capture records have three categories: transcript, events, and content. Read commands include all three unless --exclude removes a category.capture start / capture stop
Start or stop capture. --call defaults to current.capture show [call-id]
Print a finite snapshot, then exit. Omit the selector for the active call, use current, or pass a stored call ID or unique prefix. Use --recording <uuid> to select one recording session without a call selector.Text output is one readable line per record.
--format json emits one canonical record per line as JSON Lines. It is not a single object or array. The number of lines grows with the selected records, so use --since and --until when a JSON consumer needs a bounded interval.capture follow [call-id]
Follow records continuously. Without a call ID, it stays subscribed across calls. When pinned to a call or recording session, it ends with that scope.capture next [call-id]
Return one batch and exit. The first read without --cursor returns the available catch-up immediately. To wait for later records, pass the highest delivered record ID back with --cursor.If the first read is empty and provides no record ID, use --cursor 0 to start waiting.Use one foreground invocation at a time. Let your agent harness or task runner schedule the next invocation after it processes the result. Avoid an unattended shell polling loop.Live-read flags
follow and next support these flags in addition to --recording, --since, --exclude, and --timestamps:For
follow and next, --since applies only to the initial catch-up. Each JSON output line is either a canonical capture record or a synthetic status line such as {"kind":"status","status":"call_ended","call_id":"..."}. Status lines frame delivery. They are not stored capture records and have no durable record ID.A consumer should save the highest positive record id only after those records reach the model or destination. Preserve the call or recording selector and category exclusions when resuming. Never advance a checkpoint from a status line or a record with ID 0.Wake phrases
Use--wake-on with --batch to flush buffered output early. Matching is case-insensitive and applies only to finalized speech. * matches every finalized speech record. An agent_prompt flushes a batch regardless of wake phrases.capture follow watches each referenced @FILE and reloads it when it changes. capture next reads the file once. Wake phrases apply only to that command invocation.capture list
List stored calls newest first. Results include call metadata, a segment count, and resolved participants.capture search <query>
Search stored speech and shared app names, window titles, and URLs. Results are newest first.Use plain terms or quote a phrase. If the result set is broad, add participant, call, date, kind, or speaker filters.Each result identifies its
kind, call ID, timestamp, and matching snippet. Spoken results also identify the speaker and can include context_before and context_after. Content results include the app name, window title, and URL when available.capture export <destination>
Write selected records from one or more calls to one artifact file. The destination is replaced only after the complete artifact is ready. If no calls match, the command fails and leaves an existing destination untouched. On POSIX systems, the file mode is 0600.Each JSON Lines artifact record preserves the canonical capture record and adds
call_id. The global --format json changes only the command receipt; --as controls the artifact.capture delete <call-id>
Permanently delete one stored call’s conversation, events, content, and retained media. This cannot be undone.Recording sessions
Each time capture starts, Tuple creates a recording-session UUID.show, follow, next, search, and export accept --recording <uuid>. The call-capture-started and call-capture-complete triggers provide it as TUPLE_TRIGGER_RECORDING_ID.tuple notifications
The --call flag applies to every notification command and defaults to current.notifications send
Post a notice without waiting for a response. --title, --body, and --sender are required. By default, the card persists until dismissal or cancellation.--ephemeral dismisses an unnoticed card after 10 seconds. --interaction-timeout <duration> sets a value from 2s through 60s and implies --ephemeral.notifications ask
Post a decision card and wait. --title, --body, and --sender are required. --accept-label and --reject-label customize the buttons.The command prints decision and notification_id. It exits 0 only for accepted; rejected and canceled exit nonzero. The card has no timeout.notifications list
Return bounded notification containers with their current state, response, timestamps, and lifecycle.notifications follow
Follow notification lifecycle events. With --format json, each event is one JSON line. --interval <duration> buffers output.notifications cancel <notification-id>
Withdraw a card you posted. Only the user can accept or reject it.tuple whoami
Print the signed-in user’s email in text output. --format json returns id, email, full_name, and short_name.tuple state
Print a bounded orientation summary. It contains the active call, current user, contact and room counts, pending-invite count, connection state, platform, app version, and available update. Its see map points to commands for full entity lists.The summary’s call field is the same normalized Call shape returned by tuple call show --format json. Online favorite names are capped at 10. When connection.websocket_state is not connected, presence-derived counts are last-known. Pass --raw for the full daemon state.state follow
Emit a complete bounded summary whenever it changes. With --format json, each summary is one JSON line. Pass --raw for the daemon’s initial state and incremental event stream.tuple agent guide [topic]
Read operating guidance embedded in this CLI build. Run tuple agent guide for the bounded index, then read only the topic your task needs.Topics include automation, call-content, communication, connection, live-call, past-calls, safety, and troubleshooting. An app-managed agent also gets managed-agent. Availability can hide guidance for unsupported operations.Use connection for call connectivity or quality diagnosis. Use command --help for exact flags.Session-specific agent commands
The session’s generated guidance exposesagent message <text> when agent messaging is available. It sends a message to the user’s Tuple chat panel. Capture must be running for the message to enter the stored record.An app-designated managed run can expose agent attention. Its --cadence sets a duration in whole seconds and repeatable --wake-on values replace that run’s wake phrases. Use only the commands exposed for the app-provided session; reading a guide does not enable a capability.tuple connect [purpose]
Launch the configured AI agent with current-call context and embedded operating instructions. With --call, an active call supplies live context and an ended call supplies historical context. See Connect an AI agent.connect prompt [purpose]
Print the same instructions without launching an agent. It accepts --call.connect configure [harness]
Configure the default agent and its launch settings. This command requires a terminal.tuple mcp
Run the Tuple MCP server over stdin and stdout. See the MCP server page.mcp install [agent...]
Register the server with detected supported agents, or name one or more of claude, claude-desktop, and codex. Use --name to choose the server identifier.