> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Topcalls CLI

> Install the Topcalls CLI, sign in, run Topcalls tools from your terminal, and add Topcalls to Claude Code, Cursor, Codex and VS Code.

## What is the Topcalls CLI?

It's a command line for your Topcalls account. It runs the same tools as the [MCP server](https://docs.topcalls.ai/mcp/overview.md) from your terminal, and can add the Topcalls MCP server to your AI coding apps for you. For the pitch, see [topcalls.ai/cli](https://www.topcalls.ai/cli).

## How do I install it?

You need Node.js 20 or newer.

```bash theme={null}
npm install -g @topcalls/cli
```

The package is `@topcalls/cli`, with the scope. A package named plain `topcalls` or `topcalls-cli` is not ours.

## How do I sign in?

```bash theme={null}
topcalls login     # opens your browser to sign in and pick the account
topcalls whoami    # shows the account this connection uses
```

`topcalls login` opens the Topcalls sign-in page in your browser. Approve the connection there, then go back to the terminal. When it can read the account name, it shows it so you can check it is the one you expect. A name is all it can show, not proof.

If the browser doesn't open, copy the link the CLI prints. `topcalls login --no-browser` only prints the link.

## How do I add Topcalls to my AI coding apps?

```bash theme={null}
topcalls agent setup
```

This finds Claude Code, Cursor, Codex and VS Code on your computer and adds the Topcalls MCP server to each one. It prints the address it will write, asks before changing anything, keeps the other servers you have, and the first time it changes a file it saves a copy next to it as `<file>.bak-topcalls`.

| Option | What it does |
| - | - |
| `--client claude-code\|cursor\|codex\|vscode\|all` | Picks one app. The default is all that are installed. |
| `--url <address>` | Writes another Topcalls address. Without it the address is always `https://www.topcalls.ai`. `TOPCALLS_URL` is not used here. |
| `--print` | Only shows what would change. |
| `--yes` | Changes files without asking. |

No password or token is written. Claude Code, Cursor and VS Code ask you to sign in to Topcalls the first time they use a Topcalls tool. For Codex, run `codex mcp login topcalls` once after setup.

## How do I run a tool?

Every tool your account can use is a command. The CLI asks Topcalls for the list each time, so new tools show up without an update.

```bash theme={null}
topcalls tools                                   # every tool, and whether it reads or writes
topcalls list_campaigns --help                   # the flags of one tool
topcalls list_campaigns --status running
topcalls import_leads --listId 123e4567-e89b-12d3-a456-426614174000 --json '{"rows": [{"phone": "+40712345678", "name": "Ana"}]}'
```

* Write a flag exactly as `topcalls <tool> --help` shows it, for example `--listId`.
* Text, numbers, true or false and fixed choices are flags. A true or false flag on its own means true, and `--no-<flag>` means false.
* Lists and objects go in `--json '{...}'`. When both give a value, the flag wins.
* The result is printed as JSON.
* A tool that changes data first shows the account name (or says it couldn't be checked) and the arguments, then asks `Run <tool>? [y/N]`. Add `--yes` to skip the question. Without a terminal to answer in, `--yes` is required.

The tools are the ones on the [Tools](https://docs.topcalls.ai/mcp/tools.md) page.

## What do the exit codes mean?

| Code | Meaning |
| - | - |
| `0` | Done. |
| `1` | The tool or the server reported an error, you answered no (to a tool or to `agent setup`), or `logout` couldn't tell Topcalls to end a connection. |
| `2` | The command was wrong, or there was no terminal to ask in and `--yes` was not given. |
| `3` | You are not logged in, or the connection ended. |

## How do I sign out?

```bash theme={null}
topcalls logout
```

It asks Topcalls to end the connection and removes it from this computer. If Topcalls couldn't be told, it still removes it here, says so, and exits with `1`. End the connection on the **CLI & MCP** settings page in Topcalls.

## Is the CLI safe?

* The CLI can do what the connected Topcalls account allows and nothing more. A read-only connection only sees the tools that read.
* Every action goes through the same checks, limits and activity log as any other AI app connected to Topcalls. See [Security and limits](https://docs.topcalls.ai/mcp/security.md).
* You can see and end every connection on the **CLI & MCP** settings page in Topcalls.
* Sign-in uses OAuth with PKCE in your browser. The CLI never asks for your password and never takes a token on the command line.
* Credentials are stored in `~/.config/topcalls/credentials.json`, readable only by you. On macOS and Linux the CLI refuses a file other users can read. Windows doesn't get that check.
* The CLI talks only to the Topcalls address in use, over HTTPS, and never follows a redirect. It sends no analytics and doesn't check for updates.
* What a tool prints can contain text other people wrote, such as lead names or call transcripts. The CLI removes terminal control codes and invisible characters, but treat the output as untrusted when you pipe it into an AI agent.

## Which environment variables does it use?

| Variable | What it does |
| - | - |
| `TOPCALLS_URL` | Topcalls address to use instead of `https://www.topcalls.ai`. The CLI says so on every run. `agent setup` ignores it. |
| `TOPCALLS_CONFIG_DIR` | Folder for the credentials file. |
| `XDG_CONFIG_HOME` | When set, credentials go in `$XDG_CONFIG_HOME/topcalls`. |


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