Guild Ads CLI

guild-ads is the command-line interface for the Guild Ads ad network. It provides the same features as the web dashboard — creating apps, managing campaigns, booking ad slots, tracking performance, and managing publisher payouts — in a scriptable, automatable form. It is designed for both human use and AI agent integration.

Installation

npm install -g guild-ads

This installs the guild-ads binary globally. Node.js 20 or newer is required.

First login

guild-ads auth login

The command prompts for email and password interactively. In non-interactive contexts (CI, scripts, agents), pass credentials as flags:

guild-ads auth login --email [email protected] --password secret

Credentials are stored in $HOME/.config/guild-ads/auth.json with mode 0600.

If you do not have an account yet, guild-ads auth signup creates one.

JSON output

Every command accepts a --json flag that writes structured JSON to stdout. Diagnostic messages (progress, errors) always go to stderr and are never included in the JSON stream.

The --json flag can be placed before or after the subcommand:

guild-ads --json apps list
guild-ads apps list --json
GUILD_ADS_JSON=1 guild-ads apps list

All three are equivalent.

Common flows

Create a campaign and book a week

# 1. Register your app
guild-ads apps create \
  --name "My App" \
  --bundle-id com.example.app \
  --store-url https://apps.apple.com/app/id123456789 \
  --platform ios

# 2. Create an ad campaign
guild-ads campaigns create \
  --app <appId> \
  --name "Spring Launch" \
  --headline "Try My App Free" \
  --url https://apps.apple.com/app/id123456789

# 3. List available booking slots
guild-ads slots list

# 4. Book a slot
# Credits-only path (no browser required):
guild-ads book create \
  --campaign <campaignId> \
  --slot <slotId> \
  --percentage 10 \
  --apply-credits

# Mixed or cash path: the CLI opens Stripe Checkout in your browser,
# then waits for payment confirmation.

Generate an SDK token

guild-ads tokens create --app <appId> --name "Production"

The token value is shown once at creation time. Save it immediately. Retrieve the token ID later with guild-ads tokens list --app <appId>.

Redeem a promo code

guild-ads promo redeem PROMO123

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | GUILD_ADS_API_URL | https://guildads.com | Base URL for API requests. | | GUILD_ADS_SUPABASE_URL | Production URL | Supabase project URL. Override only when pointing at a different Supabase project. | | GUILD_ADS_SUPABASE_ANON_KEY | Production anon key | Supabase anon key. | | GUILD_ADS_JSON | — | Set to 1 to enable JSON output on all commands without passing --json each time. |

Use from AI agents

The CLI is designed to be safe to use non-interactively. Every command supports --json for structured output, exits with a documented status code on failure, and never prompts when all required flags are provided. Pass GUILD_ADS_JSON=1 once at the start of the session and the entire toolchain emits JSON.

Help

Run guild-ads --help to see the full command tree, or guild-ads <command> --help for a specific command.

For account help, billing questions, or to report a problem, contact us at guildads.com.

License

MIT