Using the CLI with AI Agents

Coding agents — Claude Code, Codex, Cursor and others that can run shell commands — can use the CLI directly. The CLI is built for it: JSON output, JSON errors with hints, and stable exit codes mean an agent can read results and recover from mistakes without screen-scraping.

CLI or MCP server?

Both reach the same Perspective account, but they cover different ground. The CLI wraps the External API — funnels, contacts and metrics. The MCP server also builds funnels and manages email sequences and brands.

Use the…	When
MCP server	The assistant is a chat client (Claude Desktop, ChatGPT, …) or you want tools to show up natively in the assistant.
CLI	The agent already has a shell — coding agents, CI jobs, scripts — and works with contacts or metrics, often combined with other command-line tools (jq, git, files on disk).

Install the skill

The CLI ships an Agent Skill: a SKILL.md file that tells the agent when to use the CLI, how to authenticate, how to find IDs, and which commands change live data.

perspective skill install            # for you: ~/.claude/skills/perspective/SKILL.md
perspective skill install --project  # for a repo: ./.claude/skills/perspective/SKILL.md (commit it to share)
perspective skill install --dir <skills-dir>  # any other agent that reads Agent Skills

Claude Code picks the skill up automatically and loads it when a request is about your Perspective funnels, contacts or metrics. For other agents, point them at perspective skill show | jq -r .content.

Authenticate before handing over

Store your API key before you start a session, so the agent never has to handle it:

perspective auth login   # prompts for the key

In CI, set PERSPECTIVE_API_KEY instead — see CLI Authentication.

What the skill teaches

• Run perspective auth status first and ask the user for credentials if something is missing.
• Find IDs with perspective funnels list before anything else.
• Confirm before writing. Creating or updating contacts can trigger automations and emails to real people. The skill tells the agent to run the change with --dry-run first, show you the request, and send it only after you confirm, unless you asked for that exact change. It also offers --skip-automation.
• Ask for only the fields it needs with --fields, so large contact lists don't flood the conversation.
• React to exit codes: re-authenticate on 3, on 4 or 5 re-check the ID that failed (funnel IDs with perspective funnels list, contact IDs with perspective contacts list <funnelId>), back off on 6.

Example prompts

Which of my live funnels had the best conversion rate in the last 30 days?

Export every contact from the "Webinar signup" funnel to contacts.csv.

Mark every contact from yesterday's webinar funnel whose email ends in @acme.com as qualified.