CLI / Converly CLI

Converly CLI

Set up and manage conversion tracking from the command line. The CLI is built for AI agents (Claude Code, Codex, and friends) and humans alike. Every data command prints one JSON document, so output is as easy to parse as it is to read.

Install

Terminal

npm install -g @converly/cli

Installs the converly command. Requires Node 20 or newer. To run it without installing, use npx @converly/cli.

Authentication

There are two ways to log in, plus an environment variable for CI. All three store or use a credential that is scoped for agent safety. It cannot touch billing, delete sites, or read stored ad platform credentials.

Browser login (same machine)

Terminal

converly login

Opens your browser on the same machine. You log in or create an account (new accounts start a free trial automatically, no card required) and the CLI stores its credential in ~/.converly/config.json. There’s no API key to copy around. --signup sends new users straight to account creation, and --no-open prints the URL instead of launching a browser.

Device login (headless / remote / agents)

Terminal

converly login --device

The browser login needs the browser and the CLI on the same machine. Device login removes that constraint: the CLI prints a short code and a URL, the person opens that URL on any device (their phone is fine), approves it, and the CLI receives the credential. This is the path to use on a server, in CI, or when an agent is driving the CLI and the human is elsewhere. The CLI auto-selects device login when no browser is available; --browser forces the browser flow.

CI with a provisioned key. To skip interactive login entirely, set the CONVERLY_API_KEYenvironment variable to an API key (created in Settings → API). The CLI uses it automatically and no converly login is needed.

The JSON output contract

The CLI keeps a strict contract with whatever is driving it.

Contract

stdout

one JSON doc

Every data command prints exactly one JSON document. Only help and version print plain text.

stderr

progress + errors

Human-facing progress goes to stderr. Failures print a JSON error object on stderr carrying the API’s error code.

exit code

0 or 1

0 means success. Any failure exits 1 with the JSON error on stderr.

stderr on failure

{
  "error": {
    "status": 404,
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No flow with that id."
  }
}

Three global flags work on every command. --staging targets the staging deployment. --api <origin> targets a custom deployment. --idempotency-key <key> pins the idempotency key for a POST, so running the same command twice with the same key can’t double-create (each POST otherwise generates its own key for internal retries only).

Ad platform credentials never pass through the CLI. Connecting a destination returns a Converly-hosted URL where a human authorizes the platform directly, the same handoff pattern the MCP server uses.

What’s next

Command reference

Every command, its flags, and what it returns

Driving it as an agent

The setup checklist, human handoffs, and a full worked example