> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking CLI

> Set up Pixel and server-side conversion tracking with your coding agent.

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:

```text theme={null}
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:

```bash theme={null}
npm install -g @gravity-ai/tracking
gravity-tracking login
gravity-tracking accounts
```

Sign in at [app.trygravity.com](https://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](/advertisers/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.

```bash theme={null}
# 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](/advertisers/integrations#shopify) 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](/advertisers/pixel) and [CAPI guide](/advertisers/server-conversions) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.