Skip to main content
Tuple keeps a local archive of calls you’ve captured. The Tuple app owns the archive, and the tuple CLI lets you list, search, read, and export it.Capture data stays on your machine. Use the CLI instead of opening the archive database directly.

​
Find a call

List stored calls when you know who participated or when the call happened:
Results are newest first. Each result includes call metadata, a segment count, and resolved participants. Use --after, --before, --participant, and --limit to narrow the list. The default limit is 100; pass --limit -1 for all matches.Search when you remember something someone said or shared:
Search covers spoken transcript and shared app names, window titles, and URLs. Use plain terms or quote a phrase. Narrow broad results with --kind spoken, --kind content, --speaker, --participant, --call, --after, or --before.-C <n> adds nearby speech segments around each spoken match. Content matches do not have conversation context. The default limit is 50; pass --limit -1 for all matches.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.Add --format json when a script needs structured results. List and search return JSON arrays.

​
Read the call

Pass a call ID or unique prefix from capture list or capture search to capture show:
The readable result includes transcript, lifecycle events, and shared-content metadata in record order. This is the most compact format for a broad review.Use --exclude only when the task does not need a category:
For a focused question, search within the call first. Then bound the read around the matching timestamp:
Both timestamps require RFC3339 with a zone.

​
JSON output

tuple capture show --format json emits one canonical capture record per line as JSON Lines. It does not return one object or array. Without time bounds, the output can grow to the full selected call.Each durable line includes a positive integer id, plus type, time, category, and type-specific data. Use --since and --until when a JSON consumer needs a bounded interval.A JSON read identifies people by ID. Leading user_joined records can supply names, but --since may omit them. Use the readable format when you only need attributed dialogue.

​
Inspect the shared screen

When dialogue refers to something visible but does not name it, request a stored frame at the transcript timestamp:
Use the user_id from the matching shared_content_changed record as --user. A speech record’s user_id identifies the speaker, who may not be sharing.The default behavior can move forward to finish an annotation that was in progress. Pass --exact to use the requested instant. Read stderr before trusting the image: warnings describe the frame time, timing clamps, and incomplete annotations. A stored frame can predate the requested time because Tuple stores frames when the screen changes.

​
Export calls

Export writes selected capture records to one artifact file:
--as accepts jsonl, markdown, or text. JSON Lines is the lossless default. Every line preserves a canonical capture record and adds call_id, so records remain attributable in a multi-call export.Select calls with --call, --participant, --after, and --before. Use --recording <uuid> for one exact recording session; it cannot be combined with --call.The global --format json controls the command receipt, not the artifact. Tuple replaces the destination only after the complete artifact is ready. If no calls match, the command fails and leaves an existing destination untouched. On POSIX systems, the artifact uses mode 0600.

​
Follow an active call

For an explicitly requested ongoing task, use capture next when an agent needs one batch at a time:
The first invocation without --cursor returns available catch-up immediately. After the records reach the model or destination, run the command again with the highest delivered positive record ID:
If the first read is empty and provides no record ID, use --cursor 0 to start waiting.Keep the same call or recording selector and category exclusions. Save a checkpoint only after delivery. Status lines such as {"kind":"status","status":"call_ended"} and records with ID 0 are delivery framing, not durable records, so they never advance the checkpoint.Let the agent harness or task runner schedule each foreground invocation after processing the last result. Do not use an unattended shell polling loop.Use capture follow only when the environment can consume a continuous stream. Without a call ID, it remains subscribed across calls. follow and next emit JSON Lines that mix canonical records with status framing, so consumers must distinguish id records from kind: "status" lines.For version-matched operating guidance, run tuple agent guide for the bounded topic index. Read tuple agent guide live-call and tuple agent guide call-content when the task needs live delivery details.