> ## Documentation Index > Fetch the complete documentation index at: https://docs.tuple.app/llms.txt > Use this file to discover all available pages before exploring further. # Migrate Tuple CLI and MCP integrations > Update Tuple scripts, agent skills, prompts, and MCP allowlists using the installed command and tool contracts. This page is the migration entry point for Tuple alpha testers and their agents. Give your agent this page with the files you want updated. It covers the Transcription CLI generation and the Capture CLI generation. Last verified: September 9, 2026, against installed macOS 3.2.0 and a separately built Capture-generation CLI. Select the contract exposed by your installed app and binary. ## Identify the installed contract Before editing an integration: 1. Resolve the exact executable your script or MCP configuration launches. Keep the CLI paired with its app and environment. 2. Record the app version and build. On macOS, read the app bundle's `Info.plist`. The Transcription-generation CLI rejects `--version`. 3. Read root and nested help from that executable. For MCP, initialize that server and read `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list`. Tool availability can depend on the session. 4. Select the matching column below. Update only to commands and schemas the installed executable exposes. If the app and CLI disagree, resolve the installation mismatch before testing actions. For a standard macOS installation: ```bash theme={null} ls -l /usr/local/bin/tuple /usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' /Applications/Tuple.app/Contents/Info.plist /usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' /Applications/Tuple.app/Contents/Info.plist /Applications/Tuple.app/Contents/SharedSupport/bin/tuple --help ``` Adjust the bundle path if you use a different installation. An MCP initialization response's server version identifies the server implementation, not the Tuple app release. | Contract | How to identify it | Instructions to use | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Transcription generation | Root help lists `transcription`; `transcription show --help` lists `--follow`, `--wait`, and `--with-events`. | Keep the legacy commands until the installed app and CLI support Capture. The baseline inspected for this guide is macOS 3.2.0, build `3.2.0-2026-08-12-9d2e82a561`. | | Capture generation | Root help lists `capture`; nested help exposes `capture show`, `capture follow`, `capture next`, `connect prompt`, and executable `screen`. | Apply the Capture column and verify its behavior below. Use the [command reference](/cli/commands) and [release notes](/changelog) for the installed release. | Detect the command contract instead of assuming a minimum version from this table. A root command's presence alone does not prove a flag, MCP tool, or app capability is available. ## Update commands and defaults Every command below starts with `tuple`. Preserve the exact executable path in scripts and bundled integrations. | Legacy command or option | Capture-generation replacement | Change and required action | | -------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `transcription start`, `transcription stop` | `capture start`, `capture stop` | Rename. Capture owns the call record, including transcript, events, content, stored screen media, and annotations. | | `transcription show ` | `capture show ` | Rename and default change. Read all categories unless you explicitly exclude some. | | `transcription show --follow --with-events` | `capture follow ` | Split into a dedicated reader. Events are included by default. | | `transcription show --wait` | `capture next ` | Split and semantic change. The caller owns the delivery checkpoint. | | `--cursor my-agent` on a legacy wait reader | `--cursor ` on `capture follow` or `capture next` | Semantic change. A named server-side read position is not a record ID. Start catch-up without a cursor and save the highest delivered positive ID. | | `--interval 60s` on a transcript reader | `--batch 60s` | Rename for batching. Use only on `follow` or `next`. | | `--watch-words` | Repeatable `--wake-on` | Each value is one literal phrase. A comma stays inside that phrase. Use with `--batch`. | | `transcription watch get`, `path`, `set` | Reader-owned `--wake-on @` or literal phrases | Shared state removed. A continuous follower reloads only its own specified files. `next` reads them once per invocation. | | `--with-events`, `--with-speech-markers` | Complete reads, or `--exclude events,content` for transcript-only output | Default and category change. Category selection does not reproduce every legacy record-type filter. | | `--without-speech`, `--without-chat` | Select categories, then filter individual record types in your consumer if needed | Semantic change. `--exclude transcript` removes the transcript category, not just finalized speech. Preserve chat and other records your task needs. | | `transcription list`, `search`, `delete` | `capture list`, `search`, `delete` | Rename. Deletion also removes retained media. Test reads first and preserve confirmation for deletion. | | `transcription export --format md` | `capture export --as markdown` | Destination and format change. One artifact contains all selected calls. | | Export `--format ndjson` | Export `--as jsonl` | Artifact format rename. Global `--format json` controls the receipt, not the artifact. | | `transcription set-title`, `set-summary` | `call edit --title ... --summary ...` | Relocation and merge. Set only fields you intend to change. | | `call current` | `call show` | Rename and broader lookup. A call selector can identify an active or ended call. | | `call hang-up` | `call leave` | Rename. | | `call add`, `call remove` | `call participants add`, `call participants remove` | Relocation. | | `call mute`, `call unmute` | `call mute`, `call unmute` | Unchanged CLI commands. MCP names change separately below. | | Top-level `reaction` | `call react` | Relocation. Read help for supported sounds. | | `contacts list ` | `contacts list --query ` | Positional query removed. | | `state --follow` | `state follow` | Dedicated stream command. Bounded summaries are the default; `--raw` requests the full payload. | | `screen capture -o image.jpg` | `screen -o image.jpg` | Executable command. Without `-o`, it saves an automatically named JPEG. | | `connect --print` or non-terminal implicit prompt output | `connect prompt` | Explicit command. Root `connect` launches an agent. | | `connect --config` | `connect configure [harness]` | Explicit configuration command. | | Global `--format default` or `--format table` | `--format text` | Format change. Text is the default; scripts must request JSON explicitly. | | Global `--format ndjson` | `--format json` | JSON Lines is the stream encoding, not a global format name. | The inspected 3.2.0 root help does not list `machines`. On a Capture-generation installation that exposes it, use `machines list` and pass its machine UUID to `call start `. Keep person-name resolution separate from machine IDs. Contacts and rooms retain their command groups. Verify filters through nested help. Notifications use `notifications send`, `ask`, `list`, and `cancel`; replace legacy `notifications list --follow` with `notifications follow`. Replace `contacts list --follow` with `contacts follow`. Rooms use `rooms follow` for updates and `rooms show` for one room. Verify each command separately instead of replacing flags globally. Terms such as `sessions`, `--session`, review/headless modes, and `mcp serve` can occur in older skills but are absent from the inspected baseline's public command tree. Remove those assumptions. Use Call selectors, `connect prompt` for instructions, and `tuple mcp` as the server entry point. A Capture recording selector is `--recording `; it is distinct from a connected client's session identity. In `cli.toml`, remove the obsolete `mcp_installed` bookkeeping key. Keep client registration in the client's MCP configuration. For requested ongoing participation, per-harness attention defaults use `[harness..attention]` with `batch` and `wake_on`; saving those defaults does not start a reader. See [configuration fields](/cli/config). ## Preserve Capture meaning and delivery `capture show --format json` returns a finite sequence of JSON Lines. `capture follow --format json` and `capture next --format json` also emit JSON Lines. Parse each stream line separately and distinguish durable records from framing. The categories are `transcript`, `events`, and `content`. Replace any `conversation` category assumption with the appropriate supported category. The record type `transcription_finished` still identifies finalized speech; a product command rename does not rename record types. For an explicitly requested ongoing task: 1. Keep one reader for the selected call. Its first read supplies catch-up, so a separate initial snapshot can duplicate context. 2. Deliver durable records to the model or destination. Save the highest positive record `id` only after that delivery succeeds. 3. Resume with that ID, the same call or recording selector, and the same exclusions. Retain the prior checkpoint after a delivery failure. 4. Handle `kind: "status"` separately from durable records. Carry terminal framing to the task controller so it can stop at call end. Neither framing nor an ephemeral `id: 0` advances the checkpoint. 5. Stop a call-specific reader at `call_ended`. `recording_ended` means Capture stopped and may restart within the call. A follower without a call selector stays open across calls, so use it only when the user's task covers those calls. ```bash theme={null} # First read for an explicitly requested ongoing task: tuple --format json capture next a1b2c3d4 --batch 5s # After the model receives records through ID 42: tuple --format json capture next a1b2c3d4 --cursor 42 --batch 5s ``` Replace the sample call and record IDs with observed values. Persist the returned checkpoint only after delivery succeeds. A verification read is still an undelivered read: it must not advance the saved checkpoint. If delivery succeeds but saving fails, the next read can replay those records; make your destination idempotent or deduplicate by call and record ID. A repeated batch command without an updated checkpoint can replay catch-up. A shell loop that discards stdout does not deliver context to an agent. An empty first CLI batch still needs `--cursor 0` on the next invocation to wait for records instead of repeating immediate catch-up. Keep the prior cursor after later empty batches. `--since` selects time-based catch-up. It is not a delivery checkpoint. `--until` belongs to bounded `show`, not live readers. For Capture exclusions, keep at least one category. Exports take a file destination. They preserve the previous destination if no calls match and replace it only after a complete artifact is ready. Create a private temporary directory for verification instead of overwriting an existing export. ```bash theme={null} tuple capture export ./call.jsonl --call a1b2c3d4 --as jsonl --format json tuple capture export ./call.md --call a1b2c3d4 --as markdown --exclude events,content ``` Each JSON Lines artifact record includes `call_id` so a multi-call export remains attributable. ## Update MCP configuration and allowlists Keep `tuple mcp` as the server command and point it at the matching bundled executable. Reconnect the client after changing configuration, then refresh discovery. Keep the client-specific server prefix when replacing allowlisted tool suffixes. | Legacy MCP name | Capture-generation route | Change | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `start_transcription`, `stop_transcription` | `start_capture`, `stop_capture` | Rename and complete Capture ownership. | | `get_transcription`, `get_transcription_events`, `transcription_show` | `get_capture` | Merge into a bounded Call plus records. Preserve needed categories with `exclude`. | | `transcription_list`, `transcription_search` | `list_captures`, `search_captures` | Rename. Validate argument and result schemas. | | `transcription_export` | `export_captures` | Rename and artifact change: replace `dir` with `destination`, and keep the MCP `format` field with values `jsonl`, `markdown`, or `text`. | | `set_call_title`, `set_call_summary` | `update_call` | Merge. Use `call_id` and only the metadata fields you intend to update. | | `capture_screen` | `get_screen` | Rename. Omit `at` for live pixels; provide `at` and `call_id` for a stored moment. | | `get_active_call` | `get_state` for orientation; `get_capture` for a bounded Call and its records | Removal and task-specific replacement. | | `end_call` | `leave_call` | Rename. | | `mute`, `unmute` | `mute_microphone`, `unmute_microphone` | Rename. | | `connect` tool | Read `tuple://agent/guide`, then the topic needed for the task | Removed tool. The `connect` prompt remains capability-dependent and provides context once. Neither route begins monitoring. | | `transcription_set_watch_words` | `wake_on` on advertised `next_capture`; app-owned `set_attention` where registered | Shared mutation removed. Do not add a tool the server doesn't advertise. | | State, transcript, event, notification, and archive resource aliases and subscriptions | Bounded tools and `tuple://capture/{callId}` | Removed subscriptions and duplicate resources. Explicit ongoing delivery uses an advertised reader. | Resource migrations are explicit reads: | Legacy resource URI | Capture-generation read | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `tuple://state` | `get_state`; use entity tools for full collections | | `tuple://call/{callId}/transcription` and `.json` | `get_capture` with `call_id`, or `tuple://capture/{callId}` | | `tuple://call/{callId}/events` and `.json` | `get_capture` with `exclude: ["transcript", "content"]` | | `tuple://call/{callId}/stream` and `.json` | `get_capture` for a snapshot; advertised `next_capture` for requested ongoing delivery | | `tuple://call/{callId}/notifications` and `.json` | `list_notifications` with `call_id` | | `tuple://transcription/calls` and `.json` | `list_captures` | | `tuple://transcription/call/{callId}/transcript` and `.json` | `get_capture` with `call_id` | Remove resource subscriptions and their re-read callbacks. A bounded snapshot does not replace a subscription's ongoing behavior; implement explicit reader ownership for a task that needs it. `find_discussion` and `summarize_call` prompts remain available. The `connect` prompt appears when the app permits live-call pull. Read their current argument schemas. Use ordinary search terms in examples instead of teaching agents raw database query syntax. Resources include `tuple://agent/guide`, `tuple://agent/guide/{topic}`, and `tuple://capture/{callId}`. Topics include `live-call`, `call-content`, `past-calls`, `communication`, `safety`, `connection`, `troubleshooting`, and `automation`. The app's managed mount also supplies `managed-agent`. When advertised for an attached session, `next_capture` returns a batch with `call_id`, `records`, `cursor`, and `terminal`. Omit `cursor` for initial catch-up. After delivery, repeat with the returned call and cursor. If initial catch-up is empty, `cursor: 0` starts waiting. Stop at terminal `call_ended`; retain the reader across `recording_ended`. Use `batch`, `timeout`, and `wake_on` according to the advertised schema. Agent messaging and managed attention depend on session capabilities. Refresh discovery when it changes. The app owns managed mode and its delivery loop. Reading `managed-agent` or changing an allowlist does not make an attached agent managed. ## Check scripts, skills, and prompts Search the files you own, including `AGENTS.md`, `CLAUDE.md`, skills, launch scripts, MCP configurations, and allowlists: ```bash theme={null} rg -n 'transcription|capture_screen|get_active_call|screen capture|mcp serve|connect --print|connect --config|hang-up|watch.words|--session|--format (table|default|ndjson)' . ``` Review every match in context. Preserve valid record types and any intentional legacy compatibility branch. For each edited integration: * Pin its executable and app environment. Keep separate verified branches if it supports both generations. * Replace command names, flags, destinations, structured argument fields, and response parsers together. * Make a one-time request finish after its bounded reads. Start one ongoing reader only for an explicit follow-along request. * Remove named active/passive/watch modes and unsolicited polling from prompts. Use the installed shared guides for participation instructions. * Preserve confirmation and user intent for call actions, notifications, exports, and deletion. ## Verify behavior before declaring migration complete Run these checks with the matching app and CLI. Report actual exit codes, stderr, parsed results, and any check you could not exercise. | Check | Expected result | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Nested help for every changed command and discovery for every allowlisted tool | The exact spelling, flag, and input schema exists in the installed environment. | | `tuple state --format json` | One parseable JSON value with app/call orientation. Default output is text. | | `tuple capture show --format json` | A finite JSON Lines sequence containing the selected call's complete records. Exclusions remove only the requested categories. | | A JSON Lines export to a fresh file in a private temporary directory | One artifact, attributable records, and a separate command receipt. An unmatched selection leaves an existing destination untouched. | | A call-specific batch reader followed by resume | Delivered records do not replay after their checkpoint. A simulated delivery failure resumes from the preceding checkpoint and recovers undelivered records. | | A call-specific follower through Capture stop/restart and call end | Recording end does not end the task; call end does. Check cross-call following separately if your integration uses it. | | `tuple screen -o ` and stored `--call` plus `--at` | JPEG output when media exists. Preserve reported timing/annotation caveats. Missing stored media is a data-availability error. | | Invalid input, missing call, and unavailable capability | Non-zero CLI failure or MCP error; no success-shaped result is treated as completion. | | Give an agent only this page and representative legacy files | It updates the script, skill, and allowlist, then passes the applicable execution checks without extra migration instructions. | The removed `screen_share_recording` product flag is separate from macOS **Screen Recording** permission. Capture owns stored screen media. Historical selectors remain discoverable even when a call has no stored video. Use the [CLI reference](/cli/commands), [Connect guide](/cli/connect), and [MCP reference](/cli/mcp) for ongoing use after migration.