Command Reference
Run perspective <command> --help for the same information in your terminal. Arguments in <angle brackets> are required.
Workspaces and funnels
Backed by List Workspaces.
| Command | Description |
|---|---|
perspective workspaces list | Workspaces with their funnels (campaigns), as returned by the API. |
perspective funnels list [--status draft|live|offline] [--name <text>] | Every funnel as a flat list with id, name, status, workspaceId, workspaceName — the quickest way to find a funnelId. |
Contacts
Requires an API key with crm:read / crm:write. See Contacts and CRM.
contacts list <funnelId>
| Option | Default | Description |
|---|---|---|
--page <n> | 0 | Page number, 0-based. |
--limit <n> | 50 | Page size, 1–100. |
--sort <field> | ps_converted_at | ps_converted_at, email, firstName or lastName. |
--order <dir> | desc | asc or desc. |
--all | — | Follow every page and return { data, meta: { total } }. |
contacts get <funnelId> <contactId>
Returns one contact.
contacts create <funnelId>
Needs --email or --phone. Backed by Create Contact.
| Option | Description |
|---|---|
--email, --phone, --first-name, --last-name, --status, --website, --birthday | Standard fields. |
-s, --set <key=value> | Any body field; repeatable; dots nest, e.g. -s address.city=Berlin. |
--data <json> | Full request body as JSON, @file.json, or - for stdin. Flags override it. |
--skip-automation | Do not trigger automations for the contact's initial status. |
--dry-run | Print the method, URL and body instead of sending the request. Needs no API key. |
contacts set <funnelId> <contactId> <field> <value>
Sets one field — a standard field (firstName, email, status, city, …) or any custom property. Backed by Update Contact Value. --skip-automation suppresses automation triggers, and --dry-run prints the request instead of sending it.
perspective contacts set <funnelId> <contactId> status qualified
Metrics
Requires an API key with metrics:read. See Metrics and Analytics.
| Command | Description |
|---|---|
perspective metrics kpi <funnelId> <subtype…> | One or more KPIs, or all. One KPI prints the API response as-is; several print { "data": [ … ] } in the order given, each item with its type. |
perspective metrics chart <funnelId> <subtype> [--ab-test all|original|variant] | Chart data. --ab-test only applies to page_to_page_conversion_rate. |
perspective metrics insight <funnelId> <insightId> | Answers to one question element (Insight), e.g. question_1234. |
perspective metrics subtypes | Lists valid KPI and chart subtypes (offline). |
Subtypes may be written with or without their prefix: conversion_rate, conversion-rate and kpi_conversion_rate are equivalent.
All three take a time window:
| Option | Default | Description |
|---|---|---|
--from <date> | --to minus --days | Start, ISO 8601. |
--to <date> | now | End, ISO 8601. |
--days <n> | 30 | Window length when --from is omitted. |
--tz-offset <minutes> | your local timezone | Minutes east of UTC as an integer, e.g. 120 for UTC+2. |
Auth
| Command | Description |
|---|---|
perspective auth login | Store an API key: prompts for it at a terminal, reads stdin when piped, or uses --api-key. Validated before saving. |
perspective auth status | Whether an API key is configured and its source (flag, env or config). |
perspective auth logout | Delete the stored API key. |
Agent skill
| Command | Description |
|---|---|
perspective skill install [--project] [--dir <path>] | Install SKILL.md for Claude Code (~/.claude/skills/perspective/, or ./.claude/skills/ with --project). |
perspective skill show | Print SKILL.md as {path, content}; jq -r .content gives the markdown. |