---
description: How an AI agent connects to Sofatofu, and installs the Sofatofu CLI and agent skill.
---

# Installation

Use this guide to connect an AI agent to Sofatofu. The user signs in, approves access, and chooses a workspace. Setup does not create, change, or delete CRM data.

## Check for a connection

Before you install anything, check for a connection:

- If you have the Sofatofu tools, call `auth_whoami`.
- If you have the `sofatofu` command, run `sofatofu auth whoami`.

If the check returns the user and the workspace, reuse that connection and install nothing. Go to [Before you work with CRM data](#before-you-work-with-crm-data).

A network or service error does not mean that the connection is gone, so do not set up again because of it. Try again later, or give the error to the user.

## Choose a connection

Choose one connection method so the user only needs to approve access once.

- **Connector**

  Offer the official Sofatofu connector if the app lists it. Otherwise, ask the user to add a custom MCP connector with the URL `https://sofatofu.com/mcp`.

  In Claude, [Add the Sofatofu connector](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Sofatofu&connectorUrl=https%3A%2F%2Fsofatofu.com%2Fmcp) fills in the name and URL. The user confirms, signs in, approves access, and chooses a workspace in the browser.

- **CLI:** if you can run commands, you can use the Sofatofu CLI instead. Follow [Set up the CLI](#set-up-the-cli).

If the task names a workspace, tell the user which workspace to choose.

## Set up the CLI

### Install the CLI

Install the CLI only when the `sofatofu` command is missing.

1. Run the official install script:
   - **macOS, Linux, or WSL:** `curl -fsSL https://sofatofu.com/install.sh | sh`
   - **Windows:** `irm https://sofatofu.com/install.ps1 | iex` in PowerShell
2. Use the executable path shown in the script's `Installed` line for later commands. Give any PATH instructions to the user. Do not change PATH yourself.

If installation fails or the output has no `Installed` line, stop and show the user the installer's message. Do not try another installation method. The user can use a connector instead.

### Run sofatofu init

Before the first `sofatofu init`, tell the user that the CLI sends setup data, including the setup result, CLI version, and operating system. Link to the [privacy policy](https://sofatofu.com/privacy) and explain how to turn this off before setup:

- **macOS, Linux, or WSL:** `export SOFATOFU_NO_TELEMETRY=1`
- **PowerShell:** `$env:SOFATOFU_NO_TELEMETRY = "1"`

Then run `sofatofu init`. It installs the Sofatofu skill for the supported agents that it finds, under the home folder, and then signs in.

- Add `--project` to install the skill in the project folder.
- Add `--agent <name>` to choose the agent. If `sofatofu init` finds no supported agent, its message lists the names that it accepts. Run it again with `--agent` and the name of your agent.

### Approve access

Until the user approves access, `sofatofu init` returns a link (`verification_uri_complete`) and a code (`user_code`).

1. Give the user the link and code once.
2. Run `sofatofu init` again to check.
3. If it returns the same link, the approval is still pending. Do not ask the user again.

The CLI is signed in when `sofatofu init` returns the user and the workspace.

### Start a new session

When `sofatofu init` has signed in, ask the user to start a new agent session, so that the installed skill loads. Do not ask before the sign-in is complete.

## Install only the skill

For a new setup, you can install just the skill, for example, to use it with a connector. If you can run commands, run `npx skills add https://sofatofu.com`. This installs the skill and nothing else. After it installs the skill, ask the user to start a new agent session, so that the skill loads.

## Before you work with CRM data

Check the connected user and workspace with `auth_whoami` or `sofatofu auth whoami`. Make sure that they are the ones the task needs. Then read the [Sofatofu skill](https://sofatofu.com/skills/sofatofu/SKILL.md) before the first operation.