Topcalls CLI

What is the Topcalls CLI?

It’s a command line for your Topcalls account. It runs the same tools as the MCP server from your terminal, and can add the Topcalls MCP server to your AI coding apps for you. For the pitch, see topcalls.ai/cli.

How do I install it?

You need Node.js 20 or newer.

npm install -g @topcalls/cli

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

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?

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.

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

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

Getting Started

Core Concepts

Guides

Use Cases

Integrations

MCP and CLI

What is the Topcalls CLI?

How do I install it?

How do I add Topcalls to my AI coding apps?

How do I run a tool?

What do the exit codes mean?

How do I sign out?

Is the CLI safe?

Which environment variables does it use?

What is the Topcalls CLI?

How do I install it?

How do I sign in?

How do I add Topcalls to my AI coding apps?

How do I run a tool?

What do the exit codes mean?

How do I sign out?

Is the CLI safe?

Which environment variables does it use?