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

<View title="macOS" icon="apple">
  <Warning>
    Tuple's CLI is considered **alpha**. Aspects of the feature might change as we continue to iterate on feedback.
  </Warning>

  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 transcriptions, search transcripts of 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 full command tree.

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

  <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, per-harness launch settings, and which agents you've already been offered `tuple mcp install` for — 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 not an error — the CLI falls back to built-in defaults. 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

  * [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 transcripts with `tuple transcription`.
</View>