@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_KEYenvironment variable orlogin --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.
- Open your website’s source project in your coding agent.
- Copy the prompt above and paste it into the agent. It asks for your advertiser account name first.
- 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.
Install and sign in
-
Install the CLI:
To run it without a global install, use
npx --yes @gravity-ai/trackingin place ofgravity-tracking. -
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.
-
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, runloginagain 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, rungravity-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
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:- 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-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 theGRAVITY_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.
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 exampledemo_booked.
--eventswithout--discover-eventsrequests exactly the events that you give.- With
--discover-eventsand no--events, the website candidates arePurchase,Lead,CompleteRegistration,Subscribe,StartTrial,InitiateCheckout,AddToCart,Contact, andSchedule. The app candidates areAppInstall,AppOpen, andInAppPurchase. - 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:
setup capi instead of setup full. To add your own actions, add --custom-event or --custom-event-name.
Review and deploy
- Read the changes that your agent made, and the list of missing inputs.
- Make sure that the website changes keep your consent rules.
- Make sure that the browser code reads attribution with
getCAPIData(). - Make sure that the backend sends CAPI events only after a confirmed action, with a stable event ID.
- Add your Gravity API key to the environment of your backend host.
- Deploy the changes.
- Verify the events in Events Manager. Follow the Pixel guide and the CAPI guide.
--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 tohttps://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
Afterdoctor, 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.