How to install and use the Perspective CLI?

The Perspective CLI is a command-line tool that connects your terminal to your Perspective account. It runs on the same API as the API App, so you can list funnels, read and update contacts, and pull funnel metrics without clicking through the dashboard. Everything comes back as JSON, which makes it easy to use in scripts, scheduled jobs, or an AI coding assistant.

TL;DR

Install the CLI with npm install -g @perspective-software/cli. You need Node.js 24, and it runs on Windows, macOS, and Linux.
Sign in once with perspective auth login, which opens your browser. Scripts and CI jobs use an API key instead.
Pull your data with commands like perspective funnels list, perspective contacts list <funnelId>, and perspective metrics kpi <funnelId> conversion_rate --days 30.

ℹ️ Important: The CLI needs API access, which is included in the Scale plan and the legacy Volume Plan only, and your account has to be active. On other plans, you can still install the CLI and sign in, but the contacts and metrics commands return an error. See What can I do with the API App in Perspective? for more details on API access.

What can I do with the Perspective CLI?

The CLI covers three areas: your funnels, your contacts, and your funnel metrics.

Every command prints JSON, so you can pipe it into a tool like jq, save it to a file, or feed it into your own reporting script.

It also handles pagination and date ranges for you, so you don't have to build those requests yourself. The CLI does not build or edit funnels. If you want AI to create a funnel for you, use the Perspective MCP instead.

If you want the technical detail behind all of this, our developer documentation covers the CLI in full.

Perspective CLI documentation →

How do I install the Perspective CLI?

The CLI runs on Windows, macOS, and Linux. On older versions of Node.js you may see warnings or errors during the install. Install it globally with npm, which needs Node.js 24:

npm install -g @perspective-software/cli

If you use pnpm, run pnpm add -g @perspective-software/cli instead.

Check that it worked with perspective --version.

To try a single command without installing anything, run npx @perspective-software/cli <command>.

How do I connect the CLI to my Perspective account?

There are two ways to sign in, and the CLI defaults to the browser.

Method	Command	Best for
Browser sign-in	`perspective auth login`	Working on your own machine
API key	`perspective auth login --method api-key`	Scripts, servers, CI jobs, or one key shared across your team

Check which one you are using with perspective auth status, which shows the method, where it came from, and when a browser sign-in expires. perspective auth logout deletes your stored credentials.

Your credentials are saved to ~/.config/perspective/credentials.json, in a file only you can read.

Sign in to Perspective CLI with your browser

Run perspective auth login. The CLI opens your browser on the Perspective sign-in page, the same sign-in the Perspective MCP uses, and saves the session once you are done. Your session refreshes itself, so you only sign in once.

If no browser opens, for example over SSH or inside a container, run perspective auth login --no-open instead. The CLI prints a sign-in link you can open in any browser on the same machine, and the sign-in finishes back in your terminal.

Sign in to Perspective CLI with an API key

Create the key in your Account Settings, scroll down to API Key, click Create API Key, then set a name, the Data permissions you need, and the Workspace access. Copy the key right away, because it is shown only once. The full walkthrough is in What can I do with the API App in Perspective?
Run perspective auth login --method api-key and paste the key when the terminal asks for it. Your input stays hidden, and the CLI checks the key with one test request before saving it.

Only Perspective account admins can create API keys. The permissions on the key decide which commands work: crm:read and crm:write cover the contacts commands, and metrics:read covers the metrics commands.

For CI jobs, skip the sign-in entirely and set the key as an environment variable instead: export PERSPECTIVE_API_KEY=your_key.

Which commands can I use in Perspective CLI?

Run perspective <command> --help at any time to see the options for a single command. These are the main ones:

Command	What it does
`perspective funnels list`	Lists all your funnels with their IDs, names, and status. This is the fastest way to find a funnel ID.
`perspective workspaces list`	Lists your workspaces together with the funnels inside them.
`perspective contacts list <funnelId>`	Lists the contacts of one funnel, 50 per page. Add `--all` to pull every page at once.
`perspective contacts get <funnelId> <contactId>`	Returns one single contact with all its fields.
`perspective contacts create <funnelId>`	Creates a new contact. An email address or a phone number is required.
`perspective contacts set <funnelId> <contactId> <field> <value>`	Updates one field on a contact, for example its status.
`perspective metrics kpi <funnelId> <subtype>`	Returns a KPI such as the conversion rate. Pass `all` to get every KPI at once.
`perspective metrics chart <funnelId> <subtype>`	Returns the data behind a chart, so you can plot funnel performance yourself.
`perspective metrics insight <funnelId> <insightId>`	Returns the answers people gave on one question element in your funnel.
`perspective metrics subtypes`	Lists every KPI and chart subtype you can ask for.

All metrics commands look at the last 30 days by default. Use --days 7 for a shorter window, or --from and --to with ISO dates for an exact one.

Two options work on every command. --fields keeps only the fields you name, for example --fields id,email,status, and --pretty forces indented JSON that is easier to read on screen.

Every command, option, and default value is listed in the developer documentation.

Full CLI command reference →

💡 Tip: Creating or updating a contact can trigger your automations and send real emails to real people. Add --dry-run to contacts create or contacts set first, and the CLI prints exactly what it would send without sending it.

How do I let Claude Code run the CLI for me?

Run perspective skill install to install the Perspective agent skill into ~/.claude/skills/perspective/. Claude Code then knows which commands exist and how to use them safely, so you can ask for what you want in plain English instead of writing the commands yourself.

Add --project to install the skill into the current project's .claude/skills/ folder instead, which is useful when you want it shared with your team through your repository.

Once it is installed, you can ask things like "Which of my live funnels had the best conversion rate in the last 30 days?" or "Export every contact from the Webinar signup funnel to contacts.csv."

The skill tells Claude to run a --dry-run and check with you before it changes or creates any contact.

Using the Perspective CLI with AI agents →

What do I do when a command in Perspective CLI fails?

Read the error code the CLI prints. Every failure returns JSON on stderr in the shape {"error": {"code": "forbidden", "message": ..., "hint": ...}}, so the code tells you what went wrong.

Code	What it means	What to do
`unauthenticated`	You are not signed in, or your sign-in expired.	Run `perspective auth status` to see what is stored, then `perspective auth login` to sign in again.
`forbidden`	Your plan or subscription does not cover API access, the funnel sits outside your workspaces, or your key lacks the right permission.	Read the message. "Your company's plan doesn't include the External API" and "User has no active subscription" are both billing issues. Otherwise check the funnel ID with `perspective funnels list` and the permissions on your key.
`not_found`	The funnel or contact ID does not exist.	Look the ID up again with `perspective funnels list` or `perspective contacts list`.
`usage`	A flag or argument is wrong.	Run `perspective <command> --help` to see the exact options.
`rate_limited`	You went over 100 requests per minute.	Wait a moment and run it again. The CLI already retries up to 3 times on its own.
`network`	The API could not be reached within 30 seconds.	Check your internet connection and try again.

FAQ

Do I need to be a developer to use the Perspective CLI?

You need to be comfortable running commands in a terminal, but you don't need to write any code. Installing the CLI is one command, connecting it is one more, and after that you run single commands like perspective funnels list to get your data back as JSON. If you'd rather not use a terminal at all, the Perspective MCP lets you ask for the same data in plain English inside your AI assistant.

Which Perspective plan do I need for the CLI?

The CLI needs API access, which is included in the Scale plan and in the legacy Volume Plan. The Base, Grow, and Expand plans do not include it, and neither do the other legacy plans. Your subscription also has to be active, because the API turns down a lapsed one even on Scale or Volume. Without API access, you can still install the CLI and sign in, but the contacts and metrics commands return an error. You can check what else your plan includes in Which features are included in the plans?

Can I create or edit funnels with the CLI?

No, the CLI only reads your funnel list. It cannot create, edit, publish, or delete a funnel. To build a funnel with AI, use the Perspective MCP in Claude or ChatGPT, or create it directly in Perspective. See How to create a funnel using AI? for both routes.

What is the difference between the Perspective CLI and the Perspective MCP?

The CLI is a terminal tool for reading and updating data, which makes it a good fit for scripts, exports, scheduled jobs, and reporting. The MCP connects Perspective to an AI assistant like Claude or ChatGPT and can also build funnels and manage email sequences and brands. You can use both: the MCP for building and the CLI for pulling data.

Do I need an API key to use the Perspective CLI?

No, not on your own machine. Running perspective auth login at a terminal opens your browser and signs you in to Perspective directly, so you never have to handle a key. You only need an API key for something that runs without you, like a script, a server, or a CI job, or when one key should be shared across your team, and only account admins can create those. Either way, your credentials end up in ~/.config/perspective/credentials.json, readable only by you, and perspective auth logout deletes them.

Why do I get a "forbidden" error on a funnel I can see in Perspective?

The error message tells you which cause it is. "Your company's plan doesn't include the External API" means you need the Scale plan or the legacy Volume Plan. "User has no active subscription" means your plan is right, but the subscription has lapsed, so check your billing. Any other forbidden error usually means your API key doesn't cover that funnel's workspace or lacks the permission the command needs, so check the Workspace access and Data permissions you set when you created the key. You can confirm which funnels you can reach with perspective funnels list.