# Post*back* Agent CLI Use the Post*back* CLI from a terminal or an AI agent. It connects acquisition, onboarding funnels, conversion, revenue, attribution, integrations, and safe event metadata. Read access is the default. Optional provider scopes let an agent propose and execute separately approved Apple Ads and TikTok Ads changes. > The CLI package is in private preview. Do not install similarly named packages from an unverified registry publisher. ## Setup 1. Open your app in the Post*back* dashboard. 2. Go to **Settings → Agents**. 3. Create an app-scoped token and copy it when shown. Leave both ad-change options off for read-only access, or explicitly enable only the provider the agent needs. Post*back* stores only the token hash and cannot reveal it again. 4. Run the login command and paste the token into the hidden prompt. ```bash postback auth login postback auth status --json ``` For an ephemeral agent environment, set `POSTBACK_TOKEN` instead. The CLI will use it without writing the token to disk. ## Commands ```bash 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 ``` Compact JSON is the default. Use `--pretty` for indented JSON or `--human` for concise human output where available. Successful output is written to stdout as one JSON value. Structured failures are written to stderr with a non-zero exit code. ## Approval-gated ad changes A proposal reads live provider state and returns an `approvalUrl`. It does not change the ad account. ```bash # 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 ``` The CLI also supports Apple campaign and keyword status, Apple keyword bid, TikTok campaign status and budget, and TikTok ad-group status plans. Read `postback analytics tiktok-ads` before proposing an ad pause so the exact ad ID and revenue evidence are visible. 1. Read revenue and funnel evidence. 2. Propose one bounded change with an evidence-based reason. 3. Open the returned approval URL and review the exact current and proposed values. 4. A signed-in person approves or rejects the plan in Post*back*. 5. Execute the same plan before its 30-minute window expires. 6. Confirm `status: "succeeded"` and inspect the verified provider result. Post*back* blocks no-op plans, currency changes, increases above 50 percent, Apple keyword bids under Maximize Conversions, and TikTok budget changes at the wrong campaign or ad-group ownership level. Execution re-reads provider state and stops if the plan is stale. Ambiguous provider failures are not replayed automatically. ## Security - Agent tokens are separate from mobile SDK keys. - Tokens are restricted to one app and an expiry date. - Read scopes are the default. Apple Ads and TikTok Ads write scopes are explicit and provider-specific. - The CLI cannot approve its own action plans. - Stored credentials use user-only directory and file permissions. - The CLI sends tokens only in the HTTPS Authorization header. - Raw event parameters, IP addresses, device identifiers, SDK secrets, billing, and unrelated write operations are not exposed. - Revoke a token from the same dashboard section when a device or agent no longer needs access. --- ## Docs navigation Use the Markdown URLs when reading the docs programmatically. Use the HTML URLs when you need the interactive docs UI. - [Overview](https://postback.sh/docs) ([Markdown](https://postback.sh/docs.md)) — Introduction to Post*back* - [Quickstart](https://postback.sh/docs/quickstart) ([Markdown](https://postback.sh/docs/quickstart.md)) — Get up and running in 5 minutes - [Agent CLI](https://postback.sh/docs/cli) ([Markdown](https://postback.sh/docs/cli.md)) — Revenue intelligence and controlled ad actions - [MCP for agents](https://postback.sh/docs/mcp) ([Markdown](https://postback.sh/docs/mcp.md)) — Connect an MCP-compatible agent with OAuth - [React Native](https://postback.sh/docs/react-native) ([Markdown](https://postback.sh/docs/react-native.md)) — React Native / Expo SDK reference - [iOS (Swift)](https://postback.sh/docs/ios-swift) ([Markdown](https://postback.sh/docs/ios-swift.md)) — Native Swift SDK reference - [Android (Kotlin)](https://postback.sh/docs/android) ([Markdown](https://postback.sh/docs/android.md)) — Native Android SDK reference - [Flutter](https://postback.sh/docs/flutter) ([Markdown](https://postback.sh/docs/flutter.md)) — Flutter plugin reference - [RevenueCat](https://postback.sh/docs/revenuecat) ([Markdown](https://postback.sh/docs/revenuecat.md)) — Webhook integration for subscription attribution - [Superwall](https://postback.sh/docs/superwall) ([Markdown](https://postback.sh/docs/superwall.md)) — Webhook integration for paywall attribution - [Apple Search Ads](https://postback.sh/docs/apple-search-ads) ([Markdown](https://postback.sh/docs/apple-search-ads.md)) — Keyword and ad attribution - [TikTok Ads](https://postback.sh/docs/tiktok-ads) ([Markdown](https://postback.sh/docs/tiktok-ads.md)) — Events API server-side event forwarding - [Meta Ads](https://postback.sh/docs/meta-ads) ([Markdown](https://postback.sh/docs/meta-ads.md)) — In review