Skip to main content
Release status: The published CLI is @gravity-ai/tracking@0.1.0. The @gravity-ai/tracking/server helper and one-time --token setup described below are unreleased and do not work with that version. Use browser login and the setup plan today:
Confirm the advertiser account, then have your agent implement the returned plan. For server events, use the direct API integration until the helper is released.
The Gravity Tracking CLI (@gravity-ai/tracking, command gravity-tracking) 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. The CLI reads your tracking configuration only. It does not edit files, deploy code, set secrets, change provider settings, or send conversion events. An upcoming release will provide the server conversion helper through @gravity-ai/tracking/server in the same package. This entry point is not available in the published version.

Before you start

  • Node.js 20 or later.
  • A coding agent that can run commands in the source project of your website or app.
  • One of these credentials:
    • A Gravity login as an owner or admin of an advertiser account, for the browser login.
    • Your advertiser API key, for the GRAVITY_API_KEY environment variable or login --api-key.

Set up with one prompt

The upcoming Copy request flow will include a one-time setup token to skip browser approval. Until that release, use browser login as shown above; do not pass --token to the published CLI. You can also use the general prompt below. It asks an owner or admin to approve the login in the browser.
  1. Open your website’s source project in your coding agent.
  2. Copy the prompt above and paste it into the agent. It asks for your advertiser account name first.
The plan tells the agent to do these tasks:
  • Confirm the project and the advertiser account.
  • Keep the tracking that already works.
  • Find the customer actions that your project has.
  • Prepare the Pixel and CAPI code.
The event list gives candidates only. Your project decides which actions apply. The agent reports missing settings and the decisions that you must make.

Install and sign in

  1. Install the CLI:
    To run it without a global install, use npx --yes @gravity-ai/tracking in place of gravity-tracking.
  2. Sign in:
    Your browser opens app.trygravity.com. Sign in, select your advertiser account, and select Authorize CLI. The CLI waits up to 5 minutes for you.
  3. Make sure that the CLI uses the correct account:
    The output is Account: <name>. This command does not change accounts. To use a different account, run login again and select that account.

How the CLI stores credentials

The browser login gives the CLI a read-only token for one advertiser account. The token expires after 24 hours. When it expires, run gravity-tracking login again. The CLI saves the token in the credential store of your operating system (macOS Keychain, Windows Credential Manager, or Linux Secret Service). It does not write the token to a project file. A saved login works only on the computer where you signed in. A remote coding agent must sign in, or get GRAVITY_API_KEY, in its own environment.

Use a one-time setup token

Unreleased: This section describes the upcoming setup-token flow. The published CLI rejects --token; use browser login today.
When an account owner or admin selects Copy request in Events Manager, Gravity adds a one-time setup token to the setup command in the request:
The CLI exchanges the token for a read-only token for that advertiser account. It does not open a browser, and it does not save the token in the credential store. The setup token has these limits:
  • It works one time. A second run with the same token fails.
  • It expires 30 minutes after you copy the request.
  • It gives the same read-only access as the browser login: the account, the Pixel and CAPI configuration, and the setup plan. It cannot send conversions, access GitHub repositories, or change your account.
  • Only an account owner or admin can get one. For other members, the copied request uses the browser login.
Gravity stores only a hash of the token. Each copy makes a new token. To save a login for later commands, run gravity-tracking login --token <token> with an unused token. If the token expired or was used, copy the request again, or run gravity-tracking login.

Use an API key

For CI or a headless environment, set your advertiser API key in the GRAVITY_API_KEY environment variable. This key overrides a saved login, and the CLI does not save it. To exchange the API key for a read-only token, run gravity-tracking login --api-key. Type the key at the hidden prompt. The CLI saves the token, not the key.
Keep API keys out of prompts, source code, logs, and mobile apps. The CLI token is not a CAPI key. Your deployed backend uses your API key, not the CLI token.

Choose a setup

Run the commands in the source project where your agent makes the changes. For website and app setup together, use setup full --surface both --json. The agent finds the platforms and the attribution provider in your app. You supply the provider settings that the agent cannot find. For more about app setup, see App installs. --json prints the full plan for your agent and shows no prompts. The plan never contains your API key. It does not install tracking. If an app plan has missing prerequisites, setup --json exits with code 2 and lists them. Without --json, the CLI shows the missing prerequisites as an error.

Select events

A conversion event is the name of a confirmed customer action, for example a completed purchase or a registration. A custom event is your own exact name for an action, for example demo_booked.
  • --events without --discover-events requests exactly the events that you give.
  • With --discover-events and no --events, the website candidates are Purchase, Lead, CompleteRegistration, Subscribe, StartTrial, InitiateCheckout, AddToCart, Contact, and Schedule. The app candidates are AppInstall, AppOpen, and InAppPurchase.
  • The plan keeps custom names exactly. It never changes a custom event into a standard event.
  • To request more actions, repeat --custom-event, --custom-event-name, or --goal "Business action".
  • An event name can have at most 100 characters. A goal can have at most 500 characters.

Shopify

Connect the Gravity Shopify app for the Pixel and purchase tracking on your Shopify store. The app sends Purchase, so don’t add a second sender for Shopify purchases.
  • Fully hosted on Shopify: the app tracks Purchase, and there is no code for the CLI to change. Events Manager doesn’t offer the CLI, GitHub App, or manual CAPI installers for a hosted store.
  • Custom website with Shopify checkout: use the CLI for the other actions on your site. The command in Events Manager lists every default website event except Purchase, with --discover-events:
After the Pixel is verified, the command uses setup capi instead of setup full. To add your own actions, add --custom-event or --custom-event-name.

Review and deploy

  1. Read the changes that your agent made, and the list of missing inputs.
  2. Make sure that the website changes keep your consent rules.
  3. Make sure that the browser code reads attribution with getCAPIData().
  4. Make sure that the backend sends CAPI events only after a confirmed action, with a stable event ID.
  5. Add your Gravity API key to the environment of your backend host.
  6. Deploy the changes.
  7. Verify the events in Events Manager. Follow the Pixel guide and the CAPI guide.
A plan or a successful local build does not show that events arrive. Only Events Manager shows that. --hosted-pr and resume print the link to the setup page in Events Manager. They do not run an installer from the CLI.

Command reference

logout does not revoke your API key, and it does not clear GRAVITY_API_KEY.

Setup options

Exit codes

API endpoint

The CLI connects to https://api-interface.trygravity.ai by default. Use the default for the browser login. To use a different endpoint, set --api-url or the GRAVITY_INTERFACE_API_URL environment variable.

Setup telemetry

After doctor, setup and check-payload, the CLI tells Gravity which step ran, whether it succeeded and a few counts, such as how many events the scan located. Gravity uses this to see how long setup takes and where it stalls. The CLI never sends source code, file names, payloads, credentials or personal data, and a failed telemetry call never changes the command’s result. Set GRAVITY_TRACKING_TELEMETRY=0 or DO_NOT_TRACK=1 to turn it off.

Troubleshoot