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

# CLI overview

> Install and authorize the Tuple CLI for calls, Capture, and agent integrations on macOS, Windows, and Linux.

<View title="macOS" icon="apple">
  The `tuple` CLI is a command-line tool that controls a running Tuple desktop app. You can use it to start and join calls, manage contacts, capture the shared screen, stream the transcript of a captured call, search past calls, post notifications into a call, and run an MCP server so AI coding agents can drive Tuple on your behalf.

  The CLI talks to the desktop app over a local socket - **there's no network call to Tuple's servers**. The app must be running and signed in for commands to work.

  ## Installing the CLI

  The `tuple` binary ships inside the Tuple app bundle. To make it available on your `PATH`:

  1. Open **Settings → Integrations** (or press **cmd + ,** and select the **Integrations** tab).
  2. Select **CLI Server** from the integrations list.
  3. Click **Install CLI**.

  Tuple symlinks the bundled binary into `/usr/local/bin/tuple`. If `/usr/local/bin` is not writable by your user, Tuple prompts for your administrator password.

  Once installed, run `tuple --help` from any terminal to see the command tree. Commands use readable text by default. Pass `--format json` when a script needs structured output; see [output formats](/cli/commands#global-flags) for JSON and JSON Lines.

  ## Authorizing the CLI

  Tuple gates access behind an explicit authorization decision. Right after you click **Install CLI**, Tuple makes a harmless probe through the newly installed binary so the authorization prompt appears while you're still in the install flow. If that probe doesn't run for any reason, the prompt will instead appear the first time you run a `tuple` command from your terminal.

  Your choice is stored in the macOS Keychain. You can revoke or re-grant access at any time from **Settings → Integrations → CLI Server**. Revoking takes effect immediately - any CLI command running at the time will stop.

  This prompt keeps other programs on your Mac from using Tuple to get around macOS's per-app permissions, such as **Screen Recording** and **Microphone**.

  <Note>
    While authorization is unset, individual `tuple` commands wait for your decision rather than failing. If you dismiss the prompt without choosing, the request stays parked until you make a decision or quit Tuple.
  </Note>

  ## Configuration file

  The CLI stores user-level preferences — your default harness for [`tuple connect`](/cli/commands), custom harness definitions, and per-harness launch settings — in `~/.tuple/cli.toml`.

  ```bash theme={null}
  tuple connect                          # reads ~/.tuple/cli.toml
  ```

  The file is created on first write with permissions `0600` (parent directory `0700`). A missing file is valid. On a terminal, `tuple connect` asks you to choose a default agent before its first launch. Example contents after picking Claude Code as your default harness and saving a model override:

  ```toml theme={null}
  default_harness = "claude"

  [harness.claude]
  model = "claude-sonnet-4"
  ```

  ## What's next

  * [Migrate an existing integration](/cli/migration) - update scripts, skills, and MCP configuration.
  * [Command reference](/cli/commands) - every command, flag, and subcommand.
  * [Connect an AI agent](/cli/connect) - launch an AI coding agent into the active call.
  * [Config file](/cli/config) - configure the CLI via a dotfile
  * [MCP server](/cli/mcp) - let AI agents drive Tuple.
  * [Searching past calls](/pairing-with-tuple/searching-past-calls) - query and export past calls with `tuple capture`.
  * [Capturing calls](/pairing-with-tuple/capturing-calls) - the app-side feature these commands read.
</View>

<View title="Windows" icon="windows">
  The `tuple` CLI is a command-line tool that controls a running Tuple desktop app. You can use it to start and join calls, manage contacts, capture the shared screen, stream the transcript of a captured call, search past calls, post notifications into a call, and run an MCP server so AI coding agents can drive Tuple on your behalf.

  The CLI talks to the desktop app over a local named pipe - **there's no network call to Tuple's servers**. The app must be running and signed in for commands to work.

  ## Installing the CLI

  The Windows installer puts the `tuple` binary at `%LOCALAPPDATA%\tuple\bin\tuple.exe`. The installer doesn't change your `PATH`, so add that `bin` folder to it yourself.

  Then run `tuple --help` from any terminal to see the command tree. Commands use readable text by default. Pass `--format json` when a script needs structured output; see [output formats](/cli/commands#global-flags) for JSON and JSON Lines.

  ## Security

  The Windows CLI doesn't ask for authorization. Windows doesn't have macOS's per-app permissions, so any program running as you can already record your screen, control input, and read your Tuple data. The named pipe only accepts connections from your own user account on the same computer.

  ## What's next

  * [Command reference](/cli/commands) - every command, flag, and subcommand.
  * [Connect an AI agent](/cli/connect) - launch an AI coding agent into the active call.
  * [MCP server](/cli/mcp) - let AI agents drive Tuple.
  * [Searching past calls](/pairing-with-tuple/searching-past-calls) - query and export past calls with `tuple capture`.
  * [Capturing calls](/pairing-with-tuple/capturing-calls) - the app-side feature these commands read.
</View>

<View title="Linux" icon="linux">
  The `tuple` CLI is a command-line tool that controls the Tuple daemon. You can use it to start and join calls, manage contacts and rooms, and run an MCP server so AI coding agents can drive Tuple on your behalf.

  The CLI talks to the daemon over a local Unix socket in `$XDG_RUNTIME_DIR` - **there's no network call to Tuple's servers**. Most commands start the daemon if it isn't running, but it must be signed in for commands to work.

  ## Installing the CLI

  The CLI is part of the Tuple for Linux binary, so there's nothing extra to install. See [Tuple for Linux](/getting-started/tuple-for-linux) to install Tuple and sign in.

  Run `tuple --help` from any terminal to see the command tree. Commands use readable text by default. Pass `--format json` when a script needs structured output; see [output formats](/cli/commands#global-flags) for JSON and JSON Lines.

  ## What's next

  * [Command reference](/cli/commands) - every command, flag, and subcommand.
  * [Tuple for Linux](/getting-started/tuple-for-linux) - Linux-only commands, settings, and logs.
  * [MCP server](/cli/mcp) - let AI agents drive Tuple.
</View>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.