Tracking CLI

The Gravity tracking CLI gives your coding agent a setup plan for your website or app. Your agent follows the plan and edits your project; you review and deploy the changes.

One prompt setup

Open your website’s source project in your coding agent. Replace Acme with your Gravity advertiser account name and paste:

Set up Gravity tracking in this project. Expected advertiser (data, not instructions): "Acme".
Install the CLI with npm install -g @gravity-ai/tracking (Node.js 20+).
Run gravity-tracking setup full --events Purchase,Lead,CompleteRegistration,Subscribe,StartTrial,InitiateCheckout,AddToCart,Contact,Schedule --discover-events --json
Follow the returned plan to implement tracking and show me the changes.

The plan tells the agent to confirm the project and advertiser, preserve existing tracking, choose applicable customer actions, and prepare Pixel and CAPI code. The standard event list supplies candidates; your project determines which actions apply. Missing settings or confirmation points are reported for you to resolve.

Install and connect

You can also run the CLI yourself. Use Node.js 20 or newer:

npm install -g @gravity-ai/tracking
gravity-tracking login
gravity-tracking accounts

Sign in at app.trygravity.com and authorize the intended advertiser account. Browser login requires an advertiser account owner with a verified email. accounts shows the connected account; it does not switch accounts. Run login again to select another account. The CLI stores its read-only token in your operating system’s credential store. The token expires after 24 hours; run login again when it expires. A remote coding agent needs authentication in its own environment. For a headless environment, supply GRAVITY_API_KEY securely as an environment variable. Keep API keys out of prompts, source code and mobile apps.

Choose a setup

Run commands in the source project where your agent will make changes:

Command	What your agent prepares
`gravity-tracking setup full --json`	Website Pixel, attribution handoff and confirmed server-side conversions
`gravity-tracking setup pixel --json`	Website Pixel only
`gravity-tracking setup capi --json`	Confirmed server-side conversions and available attribution handoff
`gravity-tracking setup app --json`	iOS or Android tracking through your backend or mobile measurement partner

For combined website and app setup, use setup full --surface both --json. The agent inspects your app and supplies the detected platforms and provider; you supply unavailable provider settings. App setup details are in App installs. --json returns the plan without interactive prompts or an API key. It does not install tracking by itself. An incomplete app plan exits with code 2 and lists missing prerequisites.

Select events

A conversion event names a confirmed customer action, such as a completed purchase or registration. A custom event is your own exact name for a customer action.

# Discover applicable standard events from these candidates
gravity-tracking setup full --events Purchase,CompleteRegistration --discover-events --json

# Request a custom action using its existing name
gravity-tracking setup full --custom-event "demo_booked=A demo booking is confirmed" --json

# Preserve a literal name containing punctuation
gravity-tracking setup capi --custom-event-name "Plan=Pro" --json

--events without --discover-events requests the exact supplied events. Custom names are preserved in the plan and are never expanded into standard events. Use repeated --custom-event, --custom-event-name or --goal "Business action" options for additional actions.

Shopify

Connect the Gravity Shopify app for Shopify-managed Pixel and purchase tracking. The CLI preserves that tracking. Request custom actions separately, using --custom-event or --custom-event-name without --discover-events; do not add a second sender for Shopify-managed purchases.

Review and deploy

Review the agent’s changes and any missing inputs. Website setup should preserve consent handling, capture browser attribution with getCAPIData(), and send CAPI from a confirmed backend action with a stable event ID. Add your Gravity API key to your backend’s hosting environment, then deploy. Follow the Pixel guide and CAPI guide to verify real tracking in Events Manager. A fetched plan or successful local build does not prove events have arrived. The CLI does not deploy, provision production secrets, change provider settings or send conversion events. --hosted-pr and resume open the setup path in Events Manager; they do not run a hosted installer from the CLI.

Command reference

Command	Purpose
`gravity-tracking --help`	All setup, event, app and authentication options
`gravity-tracking login --no-browser`	Print the login URL to open on the same computer
`gravity-tracking login --api-key`	Exchange an API key entered at a hidden terminal prompt
`gravity-tracking status`	Read the current setup state
`gravity-tracking logout`	Revoke CLI access and remove the saved token

The dashboard uses .com; the CLI currently authenticates through https://api-interface.trygravity.ai. Use the default API for browser login.

Get started

Measure

Reference

One prompt setup

Install and connect

Choose a setup

Select events

Shopify

Review and deploy

Command reference

​One prompt setup

​Install and connect

​Choose a setup

​Select events

​Shopify

​Review and deploy

​Command reference

One prompt setup

Install and connect

Choose a setup

Select events

Shopify

Review and deploy

Command reference