Skip to content
adscapi

CLI reference

Same package as the SDK. The CLI reads platform tokens from the environment, so the same secrets you export for createAdscapi() work here. Use it in shells, CI, and agent loops.

Install

shell
# one-shot (no install)
npx adscapi --version

# or project-local
npm i -D adscapi
npx adscapi platforms

Environment

Tokens come from process.env — never from flags. A platform is active only when its required secrets are present. check = secrets present; verify = secrets valid.

shell
# The CLI reads platform tokens from the process environment.
# Same secret names the SDK uses — see adscapi platforms for the full list.
export META_CAPI_TOKEN=…
export META_PIXEL_ID=…
export GA4_MEASUREMENT_ID=…
export GA4_API_SECRET=…
# …etc

# After interactive init:
source .env && adscapi verify

Commands

CommandWhat it does
platformsList every destination, support level, and required secrets
initGuided setup — interactive prompts or print a plan; writes .env
checkShow which platforms have secrets present right now
verifyLive-check that configured tokens actually work (hits the API)
doctorHealth check across configured platforms; nonzero exit on failure
test-eventFire one conversion event to every configured platform
offlineBatch-upload offline conversions from a CSV (Bing, Google, Meta)
creativesUpload an ad image (Meta today; Pinterest/Reddit listed)
mcpRun the MCP server over stdio for coding agents
--version / -vPrint the package version

Unknown commands print the usage banner:

text
adscapi <version>

usage:
  adscapi platforms                 list every destination + required secrets
  adscapi init [--platform meta]    guided setup — secrets, docs, verify step
  adscapi check                     show which platforms are configured
  adscapi verify [--platform meta]  live-check that configured tokens work
  adscapi doctor                    health check across configured platforms (nonzero exit on failure)
  adscapi test-event [--event ...] [--email ...] [--dry-run]
  adscapi offline --platform bing|google|meta --file conversions.csv [--dry-run]
  adscapi creatives upload --platform meta|pinterest|reddit --image <url> [--name <n>]
  adscapi mcp                       run the MCP server (stdio)
  adscapi --version

Exit codes

CommandWhen exit is nonzero
doctorNo platforms configured, or any live check returns ERR — usable as a cron / CI health gate
offlineBad flags, unreadable file, or failed > 0 in the upload result
creativesBad flags, or the platform upload fails

check, verify, platforms, and test-event print status and exit 0 even when some rows show ERR — inspect stdout.

Typical loop

shell
npx adscapi platforms          # what's supported + secret names
npx adscapi init               # prompt for missing secrets → .env
source .env
npx adscapi check              # secrets present?
npx adscapi verify             # secrets valid?
npx adscapi test-event --event purchase --email you@example.com --dry-run
npx adscapi doctor             # CI / cron health gate

Related