Driving it as an agent

The CLI is designed to be driven by an AI agent end to end. It tells you the next step, hands the human the few things only they can do, and prints machine-readable JSON at every turn. This page is the pattern to follow.

The loop: run status, act, repeat

converly statusis the brain of the setup. Run it first and after every change. It returns an ordered checklist where each item tells you its state, why it matters, the exact command to run, and whether it’s something to ask the user.

{
  "site_id": "site_2N2W…",
  "items": [
    {
      "id": "site_domain",
      "status": "action_needed",
      "what_and_why": "No website address is set. Converly rejects
        conversions from sites it doesn't recognize.",
      "next": { "kind": "ask_the_user", "question": "What is the site's address?" },
      "command": "converly sites update site_2N2W… --domain <their-domain>"
    },
    {
      "id": "install_snippet",
      "status": "action_needed",
      "what_and_why": "The Converly snippet has never been seen on the site.",
      "next": { "kind": "api_call", "method": "GET", "path": "/v1/sites/…/install-snippet" },
      "command": "converly install snippet site_2N2W…"
    },
    { "id": "flows", "status": "action_needed", "what_and_why": "No flows exist yet." },
    { "id": "first_conversion", "status": "blocked" }
  ]
}

Work the items in order. When a command is given, run it. When next.kind is ask_the_user, ask the question before proceeding. Re-run converly status to confirm each item flips to done.

What only a human can do

Three steps in a typical setup cannot be done by an agent. Design the conversation around handing them off cleanly, then confirming.

Worked example: a Webflow form to Google Ads

Fire a Google Ads conversion whenever someone submits a form on a Webflow site. The trigger (webflow-forms) is detected by the snippet, so it needs no connection of its own; only Google Ads does.

converly login --device      # approve on any device
converly status               # the ordered checklist for the site

converly sites update site_XXX --domain https://theirsite.webflow.io

converly install snippet site_XXX

converly destinations connect google-ads --site site_XXX
# → returns a URL; the user opens it and authorizes
converly handoffs wait hdf_XXX
converly destinations conversions google-ads   # pick a conversion action id

converly flows create --site site_XXX --name "Webflow lead" \
  --trigger webflow-forms --destination google-ads --conversion-id 123456

converly flows validate flow_XXX    # act on any warnings
converly flows publish flow_XXX

converly events list --limit 10     # the real submission shows up here
converly events get evt_XXX          # per-destination delivery detail