Commands

Global flags

Flag	Description
`--json`	Output as JSON instead of human-readable tables
`--verbose`, `-v`	Show request/response details for debugging

Authentication

The CLI supports two auth modes:

Mode	Command	Use case
User OAuth	`trace login`	Developer workflow, multi-app management
API Key	`trace login --api-key=...`	CI/CD pipelines, legacy setups

When both are present, the CLI prefers the OAuth token. Tokens refresh automatically.

`trace login`

Authenticate with your Trace account. Opens your browser for OAuth by default, with interactive provider selection.

# Browser OAuth — interactive provider selection (recommended)
trace login

# Skip prompt, go straight to a specific provider
trace login --provider github
trace login --provider google

# Legacy API key mode (CI/CD)
trace login --api-key tr_live_your_key_here
trace login --api-key tr_live_your_key_here --region eu

Flag	Required	Description
`--provider`	No	OAuth provider (e.g. `github`, `google`, `apple`) — skips interactive selection
`--api-key`	No	API key for legacy/CI authentication (`tr_live_...`)
`--region`	No	App region: `us` or `eu` (legacy mode only)

Available providers are fetched dynamically from the auth server. When new providers are enabled, they appear automatically — no CLI update needed.

`trace logout`

Clear authentication tokens from local config.

trace logout          # clear OAuth tokens (or API key if no OAuth)
trace logout --all    # clear both OAuth tokens and API key

`trace init`

Create a new Trace app interactively.

trace init

Prompts for: app name, Android package, iOS bundle ID, subdomain, and region. If you’re logged in with OAuth, the app is created under your account and set as active. Otherwise falls back to anonymous creation.

`trace whoami`

Show the current authenticated user or app.

trace whoami

For OAuth users, displays user ID, email, auth mode, active app, and config path. For API key users, displays app name, ID, tier, and region.

`trace apps`

`trace apps list`

List all apps in your account. Requires OAuth login.

trace apps list

Shows name, app ID, tier, region, and which app is currently active (*).

`trace apps select`

Set the active app for subsequent commands like trace metrics and trace installs.

trace apps select "My App"
trace apps select 550e8400-e29b-41d4-a716-446655440000

Matches by name (case-insensitive) or app ID.

`trace apps create`

Create a new app under your account. Alias for trace init when logged in.

trace apps create

`trace apps claim`

Link an existing unowned app to your account using its API key. Useful for migrating apps created before user accounts were available.

trace apps claim --api-key tr_live_your_key_here
trace apps claim   # uses API key from config if present

Flag	Description
`--api-key`	API key of the app to claim (`tr_live_...`)

`trace apps info`

Show current app details including tier, region, and platform identifiers.

trace apps info

`trace apps update`

Update app settings. Only specified fields are changed.

trace apps update --name "My App v2" --android-package com.example.app

Flag	Description
`--name`	App display name
`--android-package`	Android package name
`--android-cert-fingerprint`	SHA-256 cert fingerprint(s) for App Links (comma-separated)
`--ios-bundle-id`	iOS bundle identifier
`--ios-team-id`	Apple Team ID for Universal Links
`--subdomain`	Short link subdomain
`--app-store-url`	iOS App Store URL (used as default for new links)
`--play-store-url`	Google Play Store URL (used as default for new links)

`trace apps rotate-key`

Regenerate the API key. The current key is immediately invalidated. Your local config is updated automatically.

trace apps rotate-key
trace apps rotate-key -y  # skip confirmation

`trace apps rotate-salt`

Regenerate the hash salt. You must update hashSalt in your SDK TraceConfig after rotating.

trace apps rotate-salt

`trace apps dpa`

View or sign the Data Processing Agreement (DPA). Required for GDPR compliance before processing EU user data.

# Check DPA status
trace apps dpa --status

# Accept the DPA
trace apps dpa --accept --email legal@yourcompany.com

Flag	Description
`--status`	Show current DPA signing status
`--accept`	Accept the current DPA version
`--email`	Email of the person signing (required with `--accept`)

When using --accept, the CLI shows the DPA URL and asks for confirmation before recording the agreement. The full DPA text is available at traceclick.io/legal/dpa.

`trace apps upgrade`

Open Stripe Checkout to upgrade your plan.

trace apps upgrade --tier growth
trace apps upgrade --tier scale

`trace apps addon`

Add a feature add-on to your current plan. Opens Stripe Checkout in your browser.

trace apps addon --addon byol

Flag	Required	Description
`--addon`	Yes	Add-on to enable (available: `byol`)

Requires a Growth or Scale plan. BYOL is included free on Scale — this command is for Growth plan users who want to add Bring Your Own Links ($49/month).

`trace apps billing`

Open the Stripe Customer Portal to manage your subscription, update payment method, or cancel.

trace apps billing

`trace links`

`trace links create`

Create a new short link.

trace links create --deep-link-path /product/123
trace links create --deep-link-path /invite/abc \
  --campaign-id summer-2026 \
  --fallback-url https://example.com/invite \
  --expires-in-days 30

Flag	Required	Description
`--deep-link-path`	Yes	Deep link path (e.g., `/product/123`)
`--campaign-id`	No	Campaign identifier for grouping
`--fallback-url`	No	Web fallback URL
`--metadata`	No	Key=value pairs (repeatable)
`--expires-in-days`	No	Auto-expire after N days
`--sandbox`	No	Create as test link
`--qr`	No	Display QR code in terminal after creation

iOS and Android store URLs are automatically pulled from your app settings.

`trace links list`

List links with optional filtering.

trace links list
trace links list --campaign-id summer-2026 --limit 10
trace links list --sandbox  # show only sandbox links

Flag	Description
`--campaign-id`	Filter by campaign ID
`--sandbox`	Filter by sandbox status
`--offset`	Pagination offset (default: 0)
`--limit`	Number of links to return, max 100 (default: 50)

`trace links get`

Get details for a specific link.

trace links get abc123
trace links get abc123 --qr  # display QR code in terminal

Flag	Description
`--qr`	Display QR code in terminal

`trace links update`

Update a link’s settings. Only specified fields are changed.

trace links update abc123 --fallback-url https://example.com/new
trace links update abc123 --campaign-id winter-2026 --expires-in-days 90

Flag	Description
`--deep-link-path`	Deep link path
`--campaign-id`	Campaign identifier
`--ios-destination`	iOS-specific destination
`--android-destination`	Android-specific destination
`--fallback-url`	Web fallback URL
`--metadata`	Key=value pairs (repeatable)
`--expires-in-days`	Link expiration in days

`trace links delete`

Soft-delete a link.

trace links delete abc123

`trace privacy`

`trace privacy erase`

Submit a GDPR data erasure request. At least one of --ip-address or --user-id is required.

trace privacy erase --ip-address 203.0.113.1
trace privacy erase --user-id user_abc123 --email admin@example.com

Flag	Description
`--ip-address`	IP address to erase
`--user-id`	User ID to erase
`--email`	Requester email for notification

`trace privacy erase-status`

Check the status of a previously submitted erasure request.

trace privacy erase-status req_abc123

`trace privacy export`

Export all data for a user (GDPR subject access request). Always outputs JSON.

trace privacy export --user-id user_abc123
trace privacy export --ip-address 203.0.113.1

`trace debug`

`trace debug attribution`

Dry-run attribution to see matching scores without recording anything. Requires --ip-address, --user-agent, and --platform. Always outputs JSON.

trace debug attribution \
  --ip-address 203.0.113.1 \
  --user-agent "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36" \
  --platform ANDROID

trace debug attribution \
  --ip-address 203.0.113.1 \
  --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)" \
  --platform IOS \
  --device-model "iPhone15,2" \
  --screen-width 1179 \
  --screen-height 2556 \
  --screen-density 3.0 \
  --locale en-US \
  --timezone America/New_York

Flag	Required	Description
`--ip-address`	Yes	Client IP address to test
`--user-agent`	Yes	User-Agent string to test
`--platform`	Yes	`ANDROID` or `IOS`
`--os-version`	No	OS version string
`--device-model`	No	Device model name
`--screen-width`	No	Screen width in pixels
`--screen-height`	No	Screen height in pixels
`--screen-density`	No	Screen density (DPI)
`--locale`	No	Device locale (e.g., `en-US`)
`--timezone`	No	Device timezone (e.g., `America/New_York`)
`--app-version`	No	App version (default: `1.0.0`)
`--install-referrer`	No	Install referrer string (Android)
`--click-id`	No	Specific click ID to match against

`trace debug reset`

Clear sandbox attribution data for your app. Optionally scope to a specific IP.

trace debug reset
trace debug reset --ip-address 203.0.113.1

`trace webhooks`

`trace webhooks create`

Create a new webhook endpoint for your app.

trace webhooks create --url https://example.com/hook --secret whsec_abc123
trace webhooks create --url https://example.com/hook --secret whsec_abc123 --events install.attributed,install.organic

# Templated webhook (no secret needed)
trace webhooks create --url https://hooks.slack.com/services/T.../B.../xxx --template slack
trace webhooks create --url https://discord.com/api/webhooks/123/abc --template discord

Flag	Required	Description
`--url`	Yes	Webhook endpoint URL
`--secret`	When no template	HMAC-SHA256 signing secret
`--events`	No	Comma-separated event types to filter (empty = all events)
`--template`	No	Message template: `slack`, `discord`, or `teams`

`trace webhooks list`

List all webhooks configured for the app.

trace webhooks list

`trace webhooks update`

Update a webhook’s settings. Only specified fields are changed.

trace webhooks update <id> --url https://example.com/new-hook
trace webhooks update <id> --enabled=false
trace webhooks update <id> --events install.attributed,open.attributed

Flag	Description
`--url`	Webhook endpoint URL
`--secret`	Webhook signing secret
`--events`	Comma-separated event types (empty = all)
`--enabled`	Enable or disable the webhook
`--template`	Message template: `slack`, `discord`, or `teams` (empty to remove)

`trace webhooks delete`

Delete a webhook.

trace webhooks delete <id>

`trace webhooks templates`

List available webhook message templates.

trace webhooks templates

Shows template ID, name, and description. Use the template ID with trace webhooks create --template <id>.

`trace webhooks test`

Send a test webhook to a specific webhook endpoint.

trace webhooks test <id>

Returns success or failure. If delivery fails, use trace webhooks deliveries to see attempt details (HTTP status, error message, response body).

`trace webhooks deliveries`

List recent webhook delivery attempts with status, duration, and attempt number.

trace webhooks deliveries
trace webhooks deliveries --limit 10
trace webhooks deliveries --event-type install.attributed
trace webhooks deliveries --webhook-id <webhook-id>

Flag	Description
`--limit`	Number of deliveries to show, max 100 (default: `25`)
`--event-type`	Filter by event type (e.g. `install.attributed`, `open.attributed`)
`--webhook-id`	Filter by specific webhook ID

See Webhook Events for the full list of event types and payload schemas.

`trace metrics`

Show a metrics summary for the active app. Requires OAuth login and an active app.

trace metrics             # last 7 days
trace metrics --days 30   # last 30 days

Flag	Description
`--days`	Time range in days (default: `7`)

Displays installs (attributed vs organic), clicks, and events with period-over-period trend percentages.

`trace installs`

View a paginated list of installs for the active app. Requires OAuth login and an active app.

trace installs
trace installs --limit 50
trace installs --limit 50 --offset 100

Flag	Description
`--limit`	Number of installs per page, max 100 (default: `20`)
`--offset`	Pagination offset (default: `0`)

Shows platform, attribution method, confidence score, device model, campaign, and install timestamp.

`trace byol`

`trace byol snippet`

Generate a ready-to-paste <script> tag for Bring Your Own Links integration. The snippet is pre-filled with your app’s publishable key and store URLs.

# Basic snippet
trace byol snippet --deep-link-path /product/123

# With campaign and custom fallback
trace byol snippet --deep-link-path /invite/summer \
  --campaign-id summer-sale \
  --fallback-url https://yourapp.com/download

# Disable auto-redirect
trace byol snippet --deep-link-path /welcome --redirect=false

# JSON output (for scripting)
trace byol snippet --deep-link-path /product/123 --json

Flag	Default	Description
`--deep-link-path`	`/`	Deep link path for attribution
`--deep-link-params`	—	JSON key-value pairs (e.g. `'{"sku":"ABC"}'`)
`--campaign-id`	—	Campaign identifier
`--redirect`	`true`	Auto-redirect to app store after recording click
`--android-url`	App setting	Play Store URL override
`--ios-url`	App setting	App Store URL override
`--fallback-url`	—	Fallback URL for unsupported platforms

`trace version`

Print version, commit hash, and build date.

trace version