The first agent-native StackAdapt CLI: pacing, delivery-drift, and budget-waste analysis the dashboard and warehouse connectors can't answer in one call.
StackAdapt is a programmatic advertising platform. This read-only CLI queries your advertisers, campaigns, ads, audiences, and delivery reporting straight from the StackAdapt GraphQL API and answers questions the dashboard shows one screen at a time and the warehouse connectors only dump raw rows for: which campaigns are under-pacing, whose CTR has drifted, where budget is being wasted. It does not change anything in StackAdapt (read-only); it tells you what your campaigns are doing.
Printed by @sdhilip200 (Dhilip Subramanian).
Authentication
This CLI uses the StackAdapt GraphQL API, which needs a GraphQL API token (the legacy REST key will not work). To get set up:
- Ask your StackAdapt account manager for a GraphQL API token if you do not have one.
- Export it so the CLI can read it:
export STACKADAPT_API_TOKEN=your-token
- Run
stackadapt-pp-cli doctor to confirm it connects.
The token is sent as Authorization: Bearer <token>. The CLI is read-only and never modifies your campaigns.
Quick Start
# Confirms the CLI is installed and shows what a health check verifies (no token needed).
stackadapt-pp-cli doctor --dry-run
# Lists your advertisers — the top of the hierarchy and your starting point.
stackadapt-pp-cli advertisers list
# List campaigns with status and budget metadata.
stackadapt-pp-cli campaigns list --agent
# The headline answer: which campaigns are under- or over-pacing against budget.
stackadapt-pp-cli pacing --agent
# Where your ad budget is being wasted — highest spend, worst performance.
stackadapt-pp-cli bottleneck --agent
Offline store (sync, search, SQL)
StackAdapt is a live GraphQL API, but you can mirror your advertisers, campaigns,
campaign groups, ads, and segments into a local SQLite store and then work
offline — search across everything and run ad-hoc SQL without another API round
trip.
# Pull every object into the local store (advertisers, campaigns, groups, ads, segments).
stackadapt-pp-cli sync
# Sync just what you need.
stackadapt-pp-cli sync --resources advertisers,campaigns
# Substring-search synced objects by name or any field — fully offline.
stackadapt-pp-cli search "spring" --agent
stackadapt-pp-cli search acme --type advertisers
# Read-only SQL over the store (SELECT/WITH only). The 'resources' table holds
# resource_type, id, name, data (JSON), synced_at — reach into JSON with json_extract.
stackadapt-pp-cli sql "SELECT resource_type, count(*) FROM resources GROUP BY resource_type"
stackadapt-pp-cli sql "SELECT json_extract(data,'\$.channelType') AS channel, count(*) FROM resources WHERE resource_type='ads' GROUP BY channel" --json
# Serve list commands from the store instead of the API.
stackadapt-pp-cli campaigns list --data-source local
The store lives at ~/.local/share/stackadapt-pp-cli/data.db (override with the
STACKADAPT_DB environment variable). Re-running sync refreshes every object in
place. With --data-source auto (the default), list commands query the API and
fall back to the store if the API is unreachable; --data-source local reads the
store only; --data-source live skips it entirely.
Unique Features
These capabilities aren't available in any other tool for this API.
Pacing & delivery observatory
-
pacing — See which campaigns are under- or over-pacing against their budget, not just current spend.
Reach for this to catch campaigns that will overspend or underdeliver before the budget cycle ends.
stackadapt-pp-cli pacing --advertiser adv_123 --agent
-
delivery-drift — Track CTR, CPM, and spend drift week-over-week for a campaign and flag when performance degrades.
Reach for this to catch a slowly degrading campaign before it wastes budget.
stackadapt-pp-cli delivery-drift --advertiser adv_123 --days 7 --agent
Audience & efficiency
-
bottleneck — Rank the highest-spend campaigns by worst ROAS or CPA, with a reason column.
Reach for this to find where ad budget is being wasted.
stackadapt-pp-cli bottleneck --advertiser adv_123 --agent
-
stale-campaigns — Find active campaigns with zero delivery in the last N days.
Reach for this to find live-but-not-delivering campaigns.
stackadapt-pp-cli stale-campaigns --days 14 --agent
Recipes
Find under-pacing campaigns
stackadapt-pp-cli pacing --advertiser adv_123 --agent
Returns each campaign's pace (actual vs expected spend) so you can fix budget delivery before the cycle ends.
Catch a degrading campaign
stackadapt-pp-cli delivery-drift --advertiser adv_123 --days 7 --agent
Shows CTR/CPM/spend drift week-over-week and flags when performance slips.
Trim a verbose report for an agent
stackadapt-pp-cli report campaign-delivery --days 30 --agent --select records.campaign_name,records.metrics.cost,records.metrics.ctr
Delivery reports are large; --select with dotted paths returns only the fields an agent needs, saving context.
Find where budget is wasted
stackadapt-pp-cli bottleneck --advertiser adv_123 --agent
Ranks high-spend campaigns by worst ROAS/CPA with a reason column.
Usage
Run stackadapt-pp-cli --help for the full command reference and flag list.
Commands
graphql
Raw GraphQL query passthrough (advanced; prefer the typed commands)
stackadapt-pp-cli graphql - Execute a raw GraphQL query against the StackAdapt API
Output Formats
# Human-readable table (default in terminal, JSON when piped)
stackadapt-pp-cli graphql --query example-value
# JSON for scripting and agents
stackadapt-pp-cli graphql --query example-value --json
# Filter to specific fields
stackadapt-pp-cli graphql --query example-value --json --select id,name,status
# Dry run — show the request without sending
stackadapt-pp-cli graphql --query example-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
stackadapt-pp-cli graphql --query example-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
stackadapt-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/stackadapt/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
STACKADAPT_API_TOKEN | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, stackadapt-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
stackadapt-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $STACKADAPT_API_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- doctor fails with 'unauthorized' or 'invalid token' — Make sure STACKADAPT_API_TOKEN is a GraphQL API token (not a legacy REST key); request one from your StackAdapt account manager.
- advertisers list returns empty — Your token may be scoped to a different account; run
stackadapt-pp-cli account to see what it can access.
- HTTP 429 Too Many Requests — StackAdapt rate-limits the API; the CLI backs off and retries — re-run after a moment or narrow the date window.