Postback Agent CLI

Understand what drives app revenue from a terminal or AI agent. Compare acquisition, onboarding funnels, conversion, and revenue without sharing dashboard credentials or mobile SDK keys. Read access is the default; optional provider scopes add separately approved Apple Ads and TikTok Ads changes.

The CLI package is in private preview. Do not install a similarly named package unless the registry publisher is verified by Postback.

Setup

Create a scoped token

Open an app in the dashboard, then go to Settings and Agents. Create a token for that app and copy it when it appears. It cannot be revealed again. Leave both ad-change options off for read-only access, or explicitly enable only the provider the agent needs.

Sign in from the CLI

Paste the token into the hidden prompt. The token is never a command-line argument, so it stays out of shell history.

postback auth login
postback auth status --json

Use an environment token in agents

For an ephemeral environment, provide POSTBACK_TOKEN. The CLI uses it without saving a credential to disk.

Commands

Output is compact JSON by default. Use --pretty for indented output when a person is reading it.

postback apps --json
postback diagnose APP_ID --hours 24 --json
postback analytics overview APP_ID --days 30 --json
postback analytics funnels APP_ID --days 30 --json
postback analytics tiktok-ads APP_ID --days 30 --json
postback integrations status APP_ID --json
postback events list APP_ID --limit 50 --json
postback installs explain POSTBACK_ID --json

Successful JSON is written to stdout. Structured errors go to stderr and return a non-zero exit code, so agents can branch reliably.

Approval-gated ad changes

A proposal reads the provider's live state and returns an approval URL. It does not change the ad account. Open that URL, approve the exact values in Postback, then execute the same plan.

# Apple Ads campaign daily budget
postback actions propose apple-campaign-budget APP_ID \
  --org-id ORG_ID --campaign-id CAMPAIGN_ID \
  --amount 125 --currency USD \
  --reason "D30 paid ROAS supports a bounded increase"

# TikTok ad-group budget
postback actions propose tiktok-adgroup-budget APP_ID \
  --ad-group-id AD_GROUP_ID \
  --amount 60 --currency USD \
  --reason "This ad group has the strongest subscriber ROAS"

# TikTok ad status
postback actions propose tiktok-ad-status APP_ID \
  --ad-id AD_ID --status DISABLE \
  --reason "This ad spends without producing paid subscribers"

postback actions get APP_ID PLAN_ID
postback actions execute APP_ID PLAN_ID

Plans expire after 30 minutes and authorize only the values shown.
Increases above 50 percent and currency changes are blocked.
Postback re-reads provider state and stops if the plan is stale.
Execution is claimed once and the provider result is verified.
Ambiguous provider failures are never replayed automatically.

Security boundaries

Tokens are app-scoped, expiring, and revocable.
Provider write scopes are explicit and off by default.
The CLI cannot approve its own action plans.
Only a token hash is stored by Postback.
Local credentials use user-only file permissions.
Tokens travel only in the HTTPS Authorization header.
Event parameters, IP addresses, device identifiers, SDK secrets, billing, and unrelated write operations are not exposed.

Prefer a browser-approved OAuth connection? Use the hosted MCP server.

Search documentation