Skip to content

Canviq CLI

!!! info "TL;DR" The Canviq CLI lets you manage surveys, query PMF scores, and configure MCP access from the terminal. It installs from npm as @canviq/cli once the first public release ships; until then, run it from source. Source and issues live in the public canviq-cli repo.

Install

The CLI publishes to npm as @canviq/cli (the installed command is canviq):

npm install -g @canviq/cli

Availability: the canviq package ships to npm with the first public release. Until that release lands, npm install -g @canviq/cli returns a 404 Not Found. To run the CLI today, build it from source with the steps under Run from source below.

Once published, check it resolves:

canviq --version
canviq survey list

Prefer not to install globally? After the first release you can run it on demand with npx:

npx @canviq/cli survey list

Homebrew distribution (brew install revoir-software/canviq/canviq) ships with the first public release, alongside the npm package. It is not available before then. Check the canviq-cli releases for published versions and tap status.

Node.js 22.12.0 or later is required.

Run from source

Building from source is the way to run the CLI today, before the first published release. Clone the public distribution repo and build it:

git clone https://github.com/Revoir-Software/canviq-cli.git
cd canviq-cli
npm install
npm run build
node dist/index.js --version

Source and issues

The CLI is distributed from the public Revoir-Software/canviq-cli repo. Read the source, browse releases, and file bugs or feature requests in its issue tracker.

Quickstart

Five minutes from a fresh checkout to an AI agent that can query your PMF score. Every command below runs as written against a real workspace.

Step 1: Authenticate

canviq auth login

This prompts for your API key and stores it in the OS keychain. The CLI needs an agent-backed key, generated from Settings → Agents (/admin/settings/agents), not a key from the SDK page or the generic API Keys wizard. Don't have one yet? See Getting an agent-backed key.

For CI, containers, or anywhere an interactive prompt doesn't work, skip auth login and export the key instead:

export CANVIQ_API_KEY=pk_live_...

Step 2: Create your first PMF survey

RESULT=$(canviq survey pmf-create --product-name "Acme" --json)
SURVEY_ID=$(echo "$RESULT" | jq -r '.survey_id')
echo "Created survey $SURVEY_ID"

This creates and publishes the 4 standard PMF questions in one call. Each organization can have only one PMF survey per environment (live or test); a second attempt fails with an idempotency error rather than creating a duplicate. If you've already created one, list it instead:

canviq survey list --status published --json

Step 3: Check the score

Query the survey from step 2 once responses start coming in:

canviq survey pmf-score "$SURVEY_ID"

PMF Score: 43%  (218 responses)
  Very disappointed:     94
  Somewhat disappointed: 82
  Not disappointed:      42

Below the 30-response threshold, the command prints a plain-language notice instead of a score, and still exits 0.

Step 4: Connect an AI agent

canviq mcp configure

This writes Canviq into Claude Code's or Cursor's MCP server list, so an agent can query surveys and scores through natural language once CANVIQ_API_KEY is set in your shell profile. See MCP Configure for the full setup.

Who uses the CLI

Internal ops and product teams use the CLI to inspect survey results, pull PMF scores into reports, and manage survey lifecycle without opening the dashboard.

Customer developers and agent builders use the CLI to script survey workflows, feed data into CI pipelines, and configure MCP access for Claude Code and Cursor.

AI agents use canviq mcp configure to register Canviq as an MCP server, then call it through natural language, no CLI flags to memorize.

Command groups

Group What it does
auth Store and inspect API credentials
survey Create, publish, and query surveys and PMF data
question Add, update, delete, and reorder survey questions
trigger Manage survey triggers (event, manual, scheduled, page_view)
audit-logs Query the API audit log with filters and pagination
mcp Write Canviq as an MCP server into Claude Code or Cursor config

Every command accepts the global --json and --quiet flags. See Scripting and CI for the full contract.

Next steps