ops-marketing

name	ops-marketing
description	Marketing command center. Email campaigns (Klaviyo), paid ads (Meta/Google), analytics (GA4), SEO, and social media metrics. One dashboard for all marketing channels.
argument-hint	<project> [email|ads|analytics|seo|social|campaigns|setup|autopilot ...]
allowed-tools	["Bash","Read","Write","Grep","Glob","Agent","TeamCreate","SendMessage","AskUserQuestion","WebFetch","WebSearch"]
effort	medium
maxTurns	40

OPS ► MARKETING COMMAND CENTER

DNS provisioning

bin/ops-dns-provision is the canonical DNS surface for any marketing project — it covers every record an end-to-end SaaS launch typically needs, all routed through scripts/lib/cloudflare-dns.sh for GET-first idempotency. Re-running is safe; OPS_DRY_RUN=1 prints planned API calls without firing.

Subcommand	What it does
gsc <project> <domain>	Google Search Console site verification — fetches token via siteVerification/v1/token, upserts TXT at apex, calls webResource?verificationMethod=DNS_TXT to verify.
meta-aem <project> <domain>	Meta Aggregated Event Measurement — reads verification_string from /me/owned_domains, upserts facebook-domain-verification=<token> TXT at apex.
apple-pay <project> <domain>	Two modes via apple_pay.mode: static-file (default — surfaces the .well-known/apple-developer-merchantid-domain-association deploy-hook path) or stripe-dns (Stripe POST /v1/payment_method_domains).
spf <project> <domain>	Builds v=spf1 include:... <policy> from .esp.spf_includes, upserts merge-safely at apex (refuses to overwrite a foreign TXT lacking the v=spf1 marker).
dkim <project> <domain>	ESP-keyed off .esp.provider. Resend implemented (parses records[] from POST /domains, CNAME upserts). Postmark/SES stubbed.
dmarc <project> <domain>	_dmarc.<apex> TXT with v=DMARC1; p=<policy>; rua=<rua>. Defaults: policy=quarantine, rua=mailto:dmarc@<apex>.
mx <project> <domain>	Provider template keyed off .inbound.provider: google-workspace (smtp.google.com pri 1) / resend-inbound / ses (region from .inbound.region).
klaviyo-sending <project> <domain>	Klaviyo dedicated sending domain — POST /api/dedicated-sending-domains/, CNAME upserts.
audit <project> [--json]	Read-only — for each row, queries CF and reports present / absent / conflicting.
provision-all <project> [--skip <row,row>]	Idempotent full sweep.

Auth: CLOUDFLARE_API_TOKEN (Bearer, preferred) or CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL (Global key, fallback). Zone lookup: GET /zones?name=<apex> finds the zone ID. Record writes: GET-first by name+type, then PUT existing ID or POST new — never duplicate.

Apex resolver (cf_apex_for) handles co.uk-style 2nd-level TLDs (foo.co.uk → foo.co.uk) and strips proto/path/port.

Preferences schema additions

The new bin reads project-level config from $PREFS_PATH under marketing.projects.<key>:

{
  "marketing": {
    "projects": {
      "myapp": {
        "domain": "example.com",

        // Outbound email service provider (DKIM + SPF includes)
        "esp": {
          "provider": "resend", // "resend" | "postmark" | "ses"
          "credentials": "doppler:prd:RESEND_API_KEY", // cred-ref: "env:VAR" | "doppler:CFG:KEY"
          "spf_includes": ["_spf.resend.com", "_spf.klaviyo.com"], // optional; sensible defaults applied
          "spf_policy": "-all", // "-all" (strict) | "~all" (soft-fail)
        },

        // Inbound mail (MX)
        "inbound": {
          "provider": "google-workspace", // "google-workspace" | "resend-inbound" | "ses"
          "region": "us-east-1", // only used by resend-inbound / ses
        },

        // DMARC policy
        "dmarc": {
          "policy": "quarantine", // "none" | "quarantine" | "reject"
          "rua": "mailto:[e-mail]", // defaults to mailto:dmarc@<apex>
        },

        // Optional Cloudflare account override (for accounts that own multiple zones)
        "dns": {
          "cloudflare_account_id": "<your-cf-account-id>",
        },

        // Apple Pay domain registration
        "apple_pay": {
          "enabled": true,
          "mode": "static-file", // default; "stripe-dns" registers via Stripe
        },

        // Cred-refs for individual rows
        "stripe": {
          "secret_key": "env:STRIPE_SECRET_KEY", // legacy DNS provisioner key
          "api_key": "env:STRIPE_API_KEY", // P3: used by ops-marketing-autopilot stripe ROAS gate
          "account_id": "acct_<id>", // optional, only when calling on behalf of a connected acct
        },
        "meta": { "access_token": "env:META_ACCESS_TOKEN" },
        "klaviyo": {
          "private_key": "doppler:prd:KLAVIYO_API_KEY", // legacy DNS row
          "api_key": "doppler:prd:KLAVIYO_API_KEY", // P3: used by gather_klaviyo_metrics
          "account_id": "<klaviyo-account-id>", // P3: optional
          "sending_subdomain": "em.example.com",
        },
      },
    },
  },
}

Defaults are applied bash-side via ${var:-default}, so all values are optional except domain (required by audit and provision-all).

P3 — perf-data wiring (autopilot)

bin/ops-marketing-autopilot reads four perf-data sources per pass and persists them to ${OPS_DATA_DIR}/state/autopilot/<project>-{ga4-conversions,gsc-signal,klaviyo,stripe}.json:

Source	Prefs path	Helper	Purpose
GA4 conversions	marketing.projects.<key>.ga4.{property_id, sa_key_file_ref}	gather_ga4_conversions	source/medium/campaign rows for the blended bandit reward
GSC search	marketing.projects.<key>.gsc.site_url	gather_gsc_signal	rescue + ad-copy-hook candidate buckets
Klaviyo	marketing.projects.<key>.klaviyo.{api_key, account_id}	gather_klaviyo_metrics	Placed Order revenue + flow inventory
Stripe	marketing.projects.<key>.stripe.{api_key, account_id}	gather_stripe_revenue	UTM-attributed revenue per source/medium/campaign and per ad_id — ground-truth ROAS denominator + pause-rescue gate

Env knobs:

Env	Default	Effect
OPS_BANDIT_SOURCE	blended	meta → meta-only reward (legacy), ga4 → GA4 attribution only, blended → (meta + ga4)/2
OPS_PAUSE_ROAS_FLOOR	1.0	An ad with stripe_revenue ≥ floor × meta_spend is kept despite Meta CPL/CTR pause criteria
OPS_KLAVIYO_REVENUE_RATIO_FLAG	0.5	When klaviyo_revenue / paid_spend > flag, surface "email channel underweighted" in the daily report (no auto-shift)

UTM enforcement: every create_object campaign … call runs utm_validate (from scripts/lib/utm-validate.sh) on the derived (utm_source, utm_medium, utm_campaign) triple before any API mutation. Non-conforming names escalate + stage-only.

Quick examples

# Dry-run every row for a project
OPS_DRY_RUN=1 ops-dns-provision provision-all myapp

# Single row, ad-hoc domain (no prefs needed)
ops-dns-provision dmarc myapp example.com

# JSON audit for CI healthcheck
ops-dns-provision audit myapp --json
# → {"project":"myapp","domain":"example.com","zone":"...","rows":{"gsc":"present","spf":"present","dmarc":"present","mx":"present","meta_aem":"absent","dkim":"unknown"}}

# Skip rows that need provider-specific manual setup first
ops-dns-provision provision-all myapp --skip dkim,klaviyo-sending

Quick start — autonomous mode

Run /ops:marketing <project> to point-and-go:

1. ops-marketing-provision status --project <project> — what's missing
2. For each missing channel, run ops-marketing-provision provision-<channel> --project <project> (interactive only if OAuth/keys missing; otherwise idempotent)
3. Verify with ops-marketing-dash --project <project>
4. If autopilot not yet enabled, enable: ops-marketing-autopilot --project <project> --first-run-dry

Provision a brand-new project end-to-end:

# One-shot: GA4 + GSC + Instagram + Google Ads — sequential, idempotent
ops-marketing-provision provision-all --project <project>

# Iterate every project in prefs
ops-marketing-provision provision-all --all-projects

# Or individually:
ops-marketing-provision provision-ga4         --project <project> \
  --domain <domain> --account-id <YOUR_GA4_ACCOUNT_ID>
ops-marketing-provision provision-gsc         --project <project> --site https://<domain>/
ops-marketing-provision provision-instagram   --project <project>   # auto-resolves via Meta token
ops-marketing-provision provision-google-ads  --project <project>   # 4-step OAuth flow

# Check results
ops-marketing-provision status --project <project> --json
ops-marketing-dash --project <project>

provision-instagram requires marketing.projects.<key>.meta.access_token (and optional meta.app_secret for appsecret_proof signing — required when the app's "Require App Secret" setting is on, which is the default for all system-user tokens). The verb is fully idempotent: smoke-tests an existing instagram.account_id before making any API calls; pass --force to re-resolve.

provision-google-ads is a 4-step flow (each step is a no-op if the credential already exists):

1. Developer token — scans env + Doppler. If missing, writes a pending-state JSON at ${OPS_DATA_DIR}/state/marketing-provision/<project>-google-ads-pending.json and exits 1. Apply at https://ads.google.com/aw/apicenter (24–48h approval) then re-run.
2. OAuth client — scans env + Doppler. If missing, prints Cloud Console URL for creating a Desktop OAuth client.
3. Refresh token — launches a localhost HTTP server on :8080 (120s timeout), opens the Google consent URL, captures the auth code, exchanges for refresh_token, writes to Doppler as GOOGLE_ADS_<PROJECT_UPPER>_REFRESH_TOKEN.
4. Customer ID — calls v24/customers:listAccessibleCustomers, auto-detects MCC manager accounts (sets login_customer_id), writes customer_id to prefs.

Pass --skip-if-pending to skip when a dev-token application is in-flight (used by provision-all to keep the chain unblocked).

Set OPS_MARKETING_DRY_RUN=1 to print planned API calls without executing.

Runtime Context

Before executing, load available context:

1. Preferences: Read ${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json

   • timezone — display all timestamps correctly
   • klaviyo_private_key, meta_ads_token, meta_ad_account_id, ga4_property_id, google_search_console_site — check userConfig keys before env vars
   • google_ads_developer_token, google_ads_client_id, google_ads_client_secret, google_ads_refresh_token, google_ads_customer_id, google_ads_login_customer_id — Google Ads credentials

2. Daemon health: Read ${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json

   • If action_needed is not null → surface it before running any channel queries

3. Secrets: Resolve API keys via userConfig → env vars → Doppler MCP (mcp__doppler__*) → Doppler CLI fallback (see Credential Resolution section below)

CLI/API Reference

Klaviyo REST API

Endpoint	Method	Description
https://a.klaviyo.com/api/lists/?fields[list]=name,id,profile_count	GET	All lists + subscriber counts
https://a.klaviyo.com/api/campaigns/?filter=equals(messages.channel,'email')&sort=-created_at	GET	Recent campaigns
https://a.klaviyo.com/api/flows/?filter=equals(status,'live')	GET	Active flows
https://a.klaviyo.com/api/metrics/	GET	Available metrics

Auth header: Authorization: Klaviyo-API-Key ${KLAVIYO_KEY} | Revision header: revision: 2024-10-15

Meta Graph API

Endpoint	Method	Description
https://graph.facebook.com/v18.0/${META_ACCOUNT}/insights?fields=spend,...&date_preset=last_7d	GET	Account-level ad spend
https://graph.facebook.com/v18.0/${META_ACCOUNT}/campaigns?fields=name,status,insights{...}	GET	Campaign breakdown
https://graph.facebook.com/v18.0/me/accounts?fields=instagram_business_account	GET	Linked Instagram account

Auth header: Authorization: Bearer ${META_TOKEN}

Google Analytics 4 (Data API)

Endpoint	Method	Description
https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}:runReport	POST	Run custom report

Auth: gcloud ADC — GA4_TOKEN=$(gcloud auth application-default print-access-token)

Google Search Console

Endpoint	Method	Description
https://searchconsole.googleapis.com/webmasters/v3/sites/${GSC_SITE_ENCODED}/searchAnalytics/query	POST	Search performance data

Auth: Same gcloud ADC token as GA4

Agent Teams support

If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set, use Agent Teams when gathering channel data in parallel. This enables:

• Agents share context and can coordinate mid-flight
• You can steer priorities in real-time
• Agents report progress as they complete

Team setup (only when flag is enabled):

TeamCreate("marketing-team")
Agent(team_name="marketing-team", name="email-metrics", prompt="Pull Klaviyo subscriber counts, campaign stats, and flow metrics")
Agent(team_name="marketing-team", name="ads-metrics", prompt="Pull Meta Ads spend, ROAS, and campaign breakdown")
Agent(team_name="marketing-team", name="analytics-metrics", prompt="Pull GA4 sessions, conversions, and traffic sources")
Agent(team_name="marketing-team", name="seo-metrics", prompt="Pull Search Console clicks, impressions, and top queries")

If the flag is NOT set, use standard fire-and-forget subagents.

Credential Resolution

Resolve credentials in this order for each service:

Klaviyo

KLAVIYO_KEY="${KLAVIYO_PRIVATE_KEY:-$(claude plugin config get klaviyo_private_key 2>/dev/null)}"
if [ -z "$KLAVIYO_KEY" ]; then
  KLAVIYO_KEY="$(doppler secrets get KLAVIYO_PRIVATE_KEY --plain 2>/dev/null)"
fi

Meta Ads

META_TOKEN="${META_ADS_TOKEN:-$(claude plugin config get meta_ads_token 2>/dev/null)}"
META_ACCOUNT="${META_AD_ACCOUNT_ID:-$(claude plugin config get meta_ad_account_id 2>/dev/null)}"
if [ -z "$META_TOKEN" ]; then
  META_TOKEN="$(doppler secrets get META_ADS_TOKEN --plain 2>/dev/null)"
fi

GA4

GA4_PROPERTY="${GA4_PROPERTY_ID:-$(claude plugin config get ga4_property_id 2>/dev/null)}"
# GA4 uses gcloud application default credentials — check if configured:
gcloud auth application-default print-access-token 2>/dev/null

Google Search Console

GSC_SITE="${GOOGLE_SEARCH_CONSOLE_SITE:-$(claude plugin config get google_search_console_site 2>/dev/null)}"
# Uses same gcloud ADC as GA4

Google Ads

GADS_API_VERSION="v23"
GADS_DEV_TOKEN="${GOOGLE_ADS_DEVELOPER_TOKEN:-$(claude plugin config get google_ads_developer_token 2>/dev/null)}"
GADS_CLIENT_ID="${GOOGLE_ADS_CLIENT_ID:-$(claude plugin config get google_ads_client_id 2>/dev/null)}"
GADS_CLIENT_SECRET="${GOOGLE_ADS_CLIENT_SECRET:-$(claude plugin config get google_ads_client_secret 2>/dev/null)}"
GADS_REFRESH_TOKEN="${GOOGLE_ADS_REFRESH_TOKEN:-$(claude plugin config get google_ads_refresh_token 2>/dev/null)}"
GADS_CUSTOMER_ID="${GOOGLE_ADS_CUSTOMER_ID:-$(claude plugin config get google_ads_customer_id 2>/dev/null)}"
GADS_LOGIN_CUSTOMER_ID="${GOOGLE_ADS_LOGIN_CUSTOMER_ID:-$(claude plugin config get google_ads_login_customer_id 2>/dev/null)}"

# Doppler fallback
if [ -z "$GADS_REFRESH_TOKEN" ]; then
  GADS_REFRESH_TOKEN="$(doppler secrets get GOOGLE_ADS_REFRESH_TOKEN --plain 2>/dev/null)"
fi
if [ -z "$GADS_DEV_TOKEN" ]; then
  GADS_DEV_TOKEN="$(doppler secrets get GOOGLE_ADS_DEVELOPER_TOKEN --plain 2>/dev/null)"
fi

# Strip dashes from customer ID (API requires no dashes)
GADS_CUSTOMER_ID="${GADS_CUSTOMER_ID//-/}"

# Refresh access token (expires in ~1 hour — always refresh before API calls)
GADS_ACCESS_TOKEN=$(curl -s -X POST https://oauth2.googleapis.com/token \
  --data "client_id=${GADS_CLIENT_ID}" \
  --data "client_secret=${GADS_CLIENT_SECRET}" \
  --data "refresh_token=${GADS_REFRESH_TOKEN}" \
  --data "grant_type=refresh_token" | jq -r '.access_token')

# Common headers for all Google Ads API calls
GADS_HEADERS=(-H "Content-Type: application/json" -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" -H "developer-token: ${GADS_DEV_TOKEN}")
if [ -n "$GADS_LOGIN_CUSTOMER_ID" ]; then
  GADS_HEADERS+=(-H "login-customer-id: ${GADS_LOGIN_CUSTOMER_ID}")
fi

---

Organic content generators

Separate from paid ad creative gen. All outputs are drafts only — nothing auto-publishes or auto-sends (Rule 6).

Generator	CLI entry	Cron service	Enable flag
Landing-page hero variants	ops-content-landing <project>	— (on-demand)	brand.voice + brand.product + brand.target_persona + source.url in prefs
SEO blog drafts	ops-content-seo <project> [--dry-run]	content-seo-blog (Mon 09:00 UTC)	blog.enabled=true + gsc.site_url + brand.voice
Email drafts (Klaviyo flows + Resend)	ops-content-email <project> [--dry-run]	content-email-draft (Mon 10:00 UTC)	email_marketing.enabled=true + brand.voice
Social calendar (LinkedIn + X + Instagram)	ops-content-social <project> [--dry-run]	content-social-calendar (Mon 11:00 UTC)	social.enabled=true + brand.voice

All generators refuse to run if brand.voice is absent — no defaults are substituted.

Identity separation (social) — non-negotiable. Every social generator and post is project-scoped: it publishes to that project's own brand channels via marketing.projects.<project>.social.engine, never to the owner's personal/founder handle. The personal/founder identity (marketing.social_identities.personal.*, a Typefully set) is reserved for personal posts and is never a fallback for a project. A project whose social.engine.primary == null (status unprovisioned) fails closed — no post, and it never borrows the personal set or another project's channels. For upload-post brands, always pass the project's brand_targeting IDs so brand-admin personal OAuth lands on the brand page, never a personal feed. Full routing logic: /ops-socials → "Resolve the IDENTITY before anything else". No cross-posting between projects.

Output paths: ${OPS_DATA_DIR}/content/{landing,blog,email,social}/<project>/

To enable a daemon service, set enabled: true in daemon-services.default.json or via /ops:setup marketing.

---

Shopify surfaces (Shop Campaigns + Agentic storefronts)

Brand-agnostic project prefs for Shopify AI commerce and Shop pay-per-sale ads. No plaintext secrets — only cred-refs. Defaults are off / stage-only (Rule 5 / NEVER LEAK MONEY).

{
  "marketing": {
    "projects": {
      "myapp": {
        "shopify": {
          "store_url": "example.myshopify.com",
          "admin_token_ref": "env:SHOPIFY_ACCESS_TOKEN"
        },
        "shop_campaigns": {
          "enabled": false,
          "status": "not_configured", // not_configured | stage_only | active | paused
          "eligibility": "unknown", // unknown | eligible | ineligible | pending_review
          "budget": {
            "daily_cap_usd": null, // null = no auto-spend
            "currency": "USD",
            "approval": "required" // required | granted
          },
          "surfaces": {
            "shop_app": "unknown",
            "chatgpt": "unknown",
            "pinterest": "unknown",
            "microsoft_monetize": "unknown"
          },
          "notes": "",
          "last_probed_at": null
        },
        "agentic_storefronts": {
          "enabled": false,
          "channels": {
            "copilot": "unknown",
            "chatgpt": "unknown",
            "google_ai_mode": "unknown"
          },
          "last_probed_at": null
        }
      }
    }
  }
}

Rules: (1) no plaintext tokens in prefs; (2) presence of the object does not authorize spend; (3) any future mutate path requires budget.approval == "granted" and daily_cap_usd > 0 and status == "active"; (4) live channel inventory lives in /ops-ecom channels|agentic|shop.

Docs: Agentic storefronts · Shop Campaigns

Sub-command Routing

Argument parsing: $ARGUMENTS is split as <first-token> [rest...]. If <first-token> matches a known verb below, route by verb. If it looks like a project name (alphanumeric + hyphens, not a known verb), treat it as <project> and continue routing on [rest...].

Route $ARGUMENTS to the correct section below:

Input	Action
(empty), dashboard, portfolio	Visual portfolio dashboard — all projects × all configured channels (Meta, Google Ads, GA4, GSC, Resend, SNS, IG, ShipBob, Shop Campaigns, agentic storefronts, autopilot state). See ## dashboard section.
portfolio --json	Machine-readable portfolio JSON (one row per project, full channel config)
portfolio --project <name>	Full single-project config dump (every channel block)
<project>	If marketing.projects.<project>.autopilot.enabled == true → run live autopilot pass for that project. Otherwise → run bin/ops-marketing-provision provision-all --project <project> then bin/ops-marketing-autopilot --project <project> --dry-run (see ## project entry-point section)
email, klaviyo	Klaviyo email metrics
ads, meta	Meta Ads performance (read-only overview)
meta-manage, meta create-campaign, meta target, meta creative, meta rules, meta audiences, meta advantage	Meta Ads campaign management (see ## meta-manage section)
google-ads, gads	Google Ads dashboard + campaign management (see ## google-ads section)
analytics, ga4	GA4 sessions + conversions
ga4 realtime, ga4 funnel, ga4 cohort, ga4 audience, ga4 pivot	GA4 advanced analytics (see ## ga4-advanced section)
seo, gsc	Search Console metrics
social	Social media aggregator
instagram, instagram post, instagram reel, instagram story, instagram insights, instagram demographics	Instagram publishing + insights (see ## instagram section)
campaigns	Cross-channel campaign overview (all platforms)
shop-campaigns, shop_campaigns	Per-project Shop Campaigns status (prefs + optional live ecom probe) — see ## shop-campaigns
agentic-storefronts, agentic	Per-project agentic storefront prefs status (live publication probe via /ops-ecom agentic)
optimize	Cross-platform ad optimization agent
provision <project>	Idempotent full sweep — provisions GA4, GSC, Instagram, Google Ads in order. Each step is no-op if already configured. Aliases: provision-all <project>
provision-instagram <project>	Auto-resolves instagram.account_id from Meta token (uses appsecret_proof when meta.app_secret configured).
provision-google-ads <project>	4-step OAuth flow — developer token + OAuth client + refresh token (localhost callback :8080) + customer ID resolution with auto-MCC detection.
provision --all-projects	Iterate every project in prefs, run provision-all per project.
autopilot	Autonomous per-project daily ad management (see ## autopilot section)
autopilot onboard <url>	Cold-start: scrape URL, derive strategy, scaffold/stage campaigns (see ## autopilot → Autonomous onboarding)
autopilot enable <project> [--cap <usd>]	Enable autopilot for a project (see ## autopilot-enable section)
autopilot disable <project>	Disable autopilot for a project (see ## autopilot-disable section)
autopilot run <project> [--dry-run]	Run one autopilot pass directly (see ## autopilot-run section)
autopilot kill <project>	Set kill_switch for a project (see ## autopilot-kill section)
attribution	Unified attribution table (Meta + Google + Klaviyo + GA4)
setup	Configure API keys
portfolio --live	Live KPI rollup across all projects with non-zero spend or revenue
portfolio --kpis	Just the KPI section, no config-state table
portfolio --prewarm-status	Show what marketing creds exist in Doppler that aren't yet linked
<project> creative --brand=X --product=Y --audience=Z --goal=W [--num-shots=N --env=prd|dev]	Higgsfield brand asset generator. Drafts shot list, generates N images via Higgsfield API, uploads to S3, opens campaign-brief PR on my-project-operating-dashboard. See ## creative (Higgsfield) section.
Shopify Shop Campaigns: treat shop_campaigns as stage-only unless status=active and budget.approval=granted and a positive daily cap. Never auto-create Shop Campaigns budgets from autopilot in this version.

---

creative (Higgsfield)

/ops:ops-marketing <project> creative ... drafts a shot list, calls the Higgsfield API, downloads the assets, uploads them to S3, assembles a campaign-brief markdown, and opens a PR on your-org/my-project-operating-dashboard.

CLI entry: bin/ops-creative-brief (executable, source: claude-ops/bin/ops-creative-brief).

Required flags: --brand=<name> --product=<name> --audience=<desc> --goal=<desc>

Optional flags: --project=<key> (default my-project) · --env=prd|dev (default prd) · --num-shots=N (default 5, range 1..10) · --model=<higgsfield model_id> (default higgsfield-ai/soul/standard) · --dry-run · --no-pr

Higgsfield API surface (verified 2026-05-22)

• Base: https://platform.higgsfield.ai
• Auth header: Authorization: Key <HIGGSFIELD_API_KEY_ID>:<HIGGSFIELD_API_KEY_SECRET>
• Submit: POST /{model_id} body {"prompt":"...", "aspect_ratio":"16:9", "resolution":"720p"} → {status:"queued", request_id, status_url, cancel_url}
• Poll: GET /requests/{request_id}/status → status ∈ queued|in_progress|nsfw|failed|completed. On completed, response carries images[].url and/or video.url.
• Cancel: POST /requests/{request_id}/cancel (only while queued).
• Auth verified by submitting a status query for a UUID under a valid key → 404 Not found; same query under bad key → 500.

Credentials

doppler secrets get HIGGSFIELD_API_KEY_ID     --project my-project-marketing --config prd --plain
doppler secrets get HIGGSFIELD_API_KEY_SECRET --project my-project-marketing --config prd --plain

Configs: prd and dev. Keychain mirrors: security find-generic-password -a my-project -s higgsfield-api-key-id -w / -s higgsfield-api-key-secret -w. The script resolves automatically — never paste secrets into args.

Cost guardrails (NEVER LEAK MONEY)

• Plan: Higgsfield Creator = $39/mo ≈ 1200 credits. Each generation = 5..15 credits.
• Rate floor: hard ceiling of 5 generations/hour/project, enforced via mkdir-based lock on ${OPS_HIGGSFIELD_RATE_DIR:-/tmp}/.higgsfield-rate-<project>-<YYYYMMDDTHH>. Slots are reserved atomically before any HTTP call. Override only with OPS_HIGGSFIELD_RATE_LIMIT=N and a documented reason.
• FinOps usage log: ~/.creative-briefs/.usage-<YYYY-MM-DD>.log — one tab-separated line per kicked-off request (timestamp, project, model, request_id). Read by FinOps reconciliation.
• Concurrency test: tests/ops-creative-brief.test.sh spawns 6 concurrent dry-run invocations and asserts ok_count ≤ 5 and ratelimited_count ≥ 1.

S3 destination

Bucket: s3://my-project-marketing-creative/<TS>/shot-N.<ext>. The script refuses to create the bucket — if head-bucket 404s, it prints the exact aws s3 mb + public-access-block commands and exits.

Outbound comms (Rule 6)

This subcommand never sends an outbound message. The campaign brief lands as a PR on my-project-operating-dashboard for human review. the owner approves and merges manually.

Quick examples

# Dry-run (no API spend, no S3, no PR — only validates flags + shot list scaffold)
ops-creative-brief --brand=My-Project --product="DBT app" --audience="anxious millennials" \
  --goal="drive TestFlight signups" --num-shots=3 --dry-run --no-pr

# Real run against prd credentials
ops-creative-brief --brand=My-Project --product="DBT app" \
  --audience="adults 25-44 navigating burnout" \
  --goal="hero imagery for Q3 paid social launch" --num-shots=5

# Switch to dev Doppler config (separate billing context)
ops-creative-brief --env=dev --brand=My-Project --product="..." --audience="..." --goal="..."

---

Auto-link from prewarm cache

A background daemon (marketing-auth-prewarm, runs nightly at 04:23 UTC) scans every Doppler project + env + keychain + ~/.gcp for marketing credentials, classifies them into 20 categories (ads_meta, ads_google, analytics_ga4, payments_stripe, etc), and writes a cache at $OPS_DATA_DIR/marketing-auth-prewarm.json.

When setting up a new project, run:

ops-marketing-link-prewarm --project <name>

…and any auto-detectable creds get linked into marketing.projects.<name>.<category>.* as Doppler cred-refs in one shot. No per-credential prompts.

To see what would be linked without writing:

ops-marketing-portfolio --prewarm-status
OPS_MARKETING_DRY_RUN=1 ops-marketing-link-prewarm --project <name>

---

email / klaviyo

Pull Klaviyo metrics for last 30 days.

Subscriber count

curl -s "https://a.klaviyo.com/api/lists/?fields[list]=name,id,profile_count" \
  -H "Authorization: Klaviyo-API-Key ${KLAVIYO_KEY}" \
  -H "revision: 2024-10-15" | jq '.data[] | {name: .attributes.name, id: .id, count: .attributes.profile_count}'

Recent campaigns (last 10)

curl -s "https://a.klaviyo.com/api/campaigns/?filter=equals(messages.channel,'email')&sort=-created_at&page[size]=10&fields[campaign]=name,status,created_at,send_time" \
  -H "Authorization: Klaviyo-API-Key ${KLAVIYO_KEY}" \
  -H "revision: 2024-10-15" | jq '.data[] | {name: .attributes.name, status: .attributes.status, sent: .attributes.send_time}'

Flow metrics (active flows)

curl -s "https://a.klaviyo.com/api/flows/?filter=equals(status,'live')&fields[flow]=name,status,created,trigger_type" \
  -H "Authorization: Klaviyo-API-Key ${KLAVIYO_KEY}" \
  -H "revision: 2024-10-15" | jq '.data[] | {name: .attributes.name, trigger: .attributes.trigger_type}'

Key email metrics (opens, clicks, revenue via metric aggregates)

# Get metric IDs first
curl -s "https://a.klaviyo.com/api/metrics/" \
  -H "Authorization: Klaviyo-API-Key ${KLAVIYO_KEY}" \
  -H "revision: 2024-10-15" | jq '.data[] | select(.attributes.name | test("Opened Email|Clicked Email|Placed Order")) | {name: .attributes.name, id: .id}'

Output format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 EMAIL (KLAVIYO) — last 30d
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Lists:        [list_name] — [N] subscribers
 Campaigns:    [N sent] | [N drafts]
 Active Flows: [N]

 RECENT CAMPAIGNS
 [name]  [status]  sent [date]
 ...

---

ads / meta

Pull Meta Ads insights for the configured ad account.

Account-level spend (last 7 days)

curl -s "https://graph.facebook.com/v18.0/${META_ACCOUNT}/insights?fields=spend,impressions,clicks,ctr,cpc,actions,action_values&date_preset=last_7d&level=account" \
  -H "Authorization: Bearer ${META_TOKEN}" | jq '{spend: .data[0].spend, impressions: .data[0].impressions, clicks: .data[0].clicks, ctr: .data[0].ctr, cpc: .data[0].cpc}'

Campaign breakdown (last 7 days)

curl -s "https://graph.facebook.com/v18.0/${META_ACCOUNT}/campaigns?fields=name,status,daily_budget,lifetime_budget,insights{spend,impressions,clicks,actions,action_values}&date_preset=last_7d" \
  -H "Authorization: Bearer ${META_TOKEN}" | jq '.data[] | {name: .name, status: .status, spend: .insights.data[0].spend}'

ROAS calculation

From action_values array: extract action_type == "purchase" value, divide by spend.

Top performing ads (last 7d)

curl -s "https://graph.facebook.com/v18.0/${META_ACCOUNT}/ads?fields=name,adset_id,insights{spend,impressions,clicks,actions,action_values,ctr,cpc}&date_preset=last_7d&limit=10" \
  -H "Authorization: Bearer ${META_TOKEN}" | jq '.data | sort_by(.insights.data[0].spend | tonumber) | reverse | .[0:5] | .[] | {name: .name, spend: .insights.data[0].spend, ctr: .insights.data[0].ctr}'

Output format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 META ADS — last 7d
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Spend:       $[X]
 ROAS:        [X]x
 Purchases:   [N]  ($[X] revenue)
 Impressions: [N]  CTR: [X]%
 CPC:         $[X]

 CAMPAIGNS
 [name]  [status]  $[spend]  [roas]x ROAS
 ...

 TOP ADS (by spend)
 [name]  $[spend]  [ctr]% CTR

---

meta-manage

Full Meta Ads campaign management. Uses same META_TOKEN and META_ACCOUNT credentials as read-only ads section.

Credential check: If META_TOKEN is empty, print Meta Ads not configured. Run /ops:marketing setup. and stop.

Route $ARGUMENTS within meta-manage:

Input	Action
create-campaign	Create a new campaign (always PAUSED)
target <ADSET_ID>	Configure ad set targeting
creative <CAMPAIGN_ID>	Upload image + create ad with copy
rules	List / create automation rules
audiences	Create custom or lookalike audiences
advantage	Create Advantage+ AI-optimized campaign

create-campaign

Collect via AskUserQuestion (max 4 options each call):

1. Campaign objective — [OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS]
2. Daily budget in dollars (free text)
3. Campaign name (free text)

Then confirm via AskUserQuestion: "Create Meta campaign '<NAME>' with $<BUDGET>/day budget?" options [Create, Cancel]

BUDGET_CENTS=$(awk "BEGIN {printf \"%d\", ${BUDGET_DOLLARS} * 100}")
curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/campaigns" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "name=${CAMPAIGN_NAME}" \
  -F "objective=${OBJECTIVE}" \
  -F "status=PAUSED" \
  -F "special_ad_categories=[]" \
  -F "daily_budget=${BUDGET_CENTS}" | jq '{id: .id, error: .error.message}'

Print: Campaign "${CAMPAIGN_NAME}" created (ID: <ID>, status: PAUSED, budget: $<BUDGET>/day). Enable via Meta Ads Manager or add ad sets first.

If error, print the error message.

target <ADSET_ID>

Configure targeting for an existing ad set. Collect via AskUserQuestion:

1. Target countries (comma-separated ISO codes, e.g. US,CA,GB) — free text
2. Age range: [18-34, 25-54, 35-65, 18-65]
3. Gender: [All, Men only, Women only, Skip]

# Build geo_locations JSON
GEO_JSON=$(echo "$COUNTRIES" | tr ',' '\n' | jq -Rc '.' | jq -sc '{"countries": .}')

# Build targeting spec
TARGETING_JSON=$(jq -n \
  --argjson geo "$GEO_JSON" \
  --arg age_min "$AGE_MIN" \
  --arg age_max "$AGE_MAX" \
  '{
    geo_locations: $geo,
    age_min: ($age_min | tonumber),
    age_max: ($age_max | tonumber)
  }')

# Add gender filter if requested
if [ "$GENDER" = "Men only" ]; then
  TARGETING_JSON=$(echo "$TARGETING_JSON" | jq '. + {"genders": [1]}')
elif [ "$GENDER" = "Women only" ]; then
  TARGETING_JSON=$(echo "$TARGETING_JSON" | jq '. + {"genders": [2]}')
fi

curl -s -X POST "https://graph.facebook.com/v20.0/${ADSET_ID}" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "targeting=${TARGETING_JSON}" | jq '{success: .success, error: .error.message}'

Print: Ad set ${ADSET_ID} targeting updated: ${COUNTRIES}, ages ${AGE_MIN}-${AGE_MAX}${GENDER_LABEL}.

creative <CAMPAIGN_ID>

Upload an image and create an ad. Collect via AskUserQuestion:

1. Image file path or URL (free text)
2. Ad set ID to attach the ad to (free text)
3. Primary text (ad copy, free text — up to 125 characters recommended)

Then collect headline (free text, up to 40 characters) via a second AskUserQuestion.

# Step 1: Upload image
if [[ "$IMAGE_INPUT" == http* ]]; then
  # Upload by URL
  UPLOAD_RESP=$(curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/adimages" \
    -H "Authorization: Bearer ${META_TOKEN}" \
    -F "url=${IMAGE_INPUT}")
else
  # Upload by file (multipart)
  UPLOAD_RESP=$(curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/adimages" \
    -H "Authorization: Bearer ${META_TOKEN}" \
    -F "filename=@${IMAGE_INPUT}")
fi
IMAGE_HASH=$(echo "$UPLOAD_RESP" | jq -r '.images | to_entries[0].value.hash // empty')

if [ -z "$IMAGE_HASH" ]; then
  echo "Image upload failed: $(echo "$UPLOAD_RESP" | jq -r '.error.message // "unknown error"')"
  exit 0
fi

# Resolve the Facebook Page ID. Meta's `object_story_spec.page_id` requires a
# real Page ID — the ad account ID (with `act_` stripped) is NOT a Page ID and
# the API call will fail. Require META_PAGE_ID in env or plugin prefs.
META_PAGE_ID="${META_PAGE_ID:-$(claude plugin config get meta_page_id 2>/dev/null || echo "")}"
if [ -z "$META_PAGE_ID" ]; then
  echo "META_PAGE_ID is required to create an ad creative. Set it via:"
  echo "  claude plugin config set meta_page_id <your_fb_page_id>"
  echo "Find your Page ID at https://www.facebook.com/<your-page>/about_profile_transparency"
  exit 0
fi

# Step 2: Create ad creative
CREATIVE_RESP=$(curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/adcreatives" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "name=Creative for ${AD_NAME}" \
  -F "object_story_spec={\"page_id\": \"${META_PAGE_ID}\", \"link_data\": {\"image_hash\": \"${IMAGE_HASH}\", \"message\": \"${PRIMARY_TEXT}\", \"name\": \"${HEADLINE}\"}}")
CREATIVE_ID=$(echo "$CREATIVE_RESP" | jq -r '.id // empty')

if [ -z "$CREATIVE_ID" ]; then
  echo "Creative creation failed: $(echo "$CREATIVE_RESP" | jq -r '.error.message // "unknown error"')"
  exit 0
fi

# Step 3: Create ad (status PAUSED — Rule 5)
curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/ads" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "name=${AD_NAME}" \
  -F "adset_id=${ADSET_ID}" \
  -F "creative={\"creative_id\": \"${CREATIVE_ID}\"}" \
  -F "status=PAUSED" | jq '{id: .id, error: .error.message}'

Print: Ad created (ID: <ID>, creative: <CREATIVE_ID>, status: PAUSED). Enable via Meta Ads Manager when ready.

rules

List existing rules or create a new automation rule.

List rules:

curl -s "https://graph.facebook.com/v20.0/${META_ACCOUNT}/adrules_library?fields=name,status,evaluation_spec,execution_spec" \
  -H "Authorization: Bearer ${META_TOKEN}" | jq '.data[] | {id: .id, name: .name, status: .status}'

Create rule (prompt via AskUserQuestion):

1. Rule type: [Pause low performers, Scale winners, Increase budget, Decrease budget]

For "Pause low performers":

# Pause ads where CPA > $50 and spend > $20 in last 7 days
curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/adrules_library" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pause high CPA ads",
    "schedule_spec": {"schedule_type": "SEMI_HOURLY"},
    "evaluation_spec": {
      "evaluation_type": "SCHEDULE",
      "filters": [
        {"field": "cost_per_result", "value": [50], "operator": "GREATER_THAN"},
        {"field": "spent", "value": [20], "operator": "GREATER_THAN"},
        {"field": "entity_type", "value": ["AD"], "operator": "EQUAL"},
        {"field": "time_preset", "value": ["LAST_7_DAYS"], "operator": "EQUAL"}
      ]
    },
    "execution_spec": {
      "execution_type": "PAUSE"
    },
    "status": "ENABLED"
  }' | jq '{id: .id, error: .error.message}'

For "Scale winners":

# Increase budget 20% for ad sets with ROAS > 3x in last 7 days
curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/adrules_library" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Scale winning ad sets",
    "schedule_spec": {"schedule_type": "DAILY"},
    "evaluation_spec": {
      "evaluation_type": "SCHEDULE",
      "filters": [
        {"field": "purchase_roas", "value": [3], "operator": "GREATER_THAN"},
        {"field": "entity_type", "value": ["ADSET"], "operator": "EQUAL"},
        {"field": "time_preset", "value": ["LAST_7_DAYS"], "operator": "EQUAL"}
      ]
    },
    "execution_spec": {
      "execution_type": "INCREASE_BUDGET",
      "execution_options": [{"field": "budget_value", "value": "20", "operator": "PERCENTAGE"}]
    },
    "status": "ENABLED"
  }' | jq '{id: .id, error: .error.message}'

Print: Rule created (ID: <ID>). Runs semi-hourly and will auto-pause ads with CPA > $50.

audiences

Create Custom Audience or Lookalike Audience.

Prompt via AskUserQuestion:

1. Audience type: [Custom — website, Custom — customer list, Lookalike, Skip]

Custom — website (Pixel-based):

curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/customaudiences" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website visitors — last 30 days",
    "subtype": "WEBSITE",
    "retention_days": 30,
    "rule": {"inclusions": {"operator": "or", "rules": [{"event_sources": [{"id": "<PIXEL_ID>", "type": "pixel"}], "retention_seconds": 2592000, "filter": {"operator": "and", "filters": [{"field": "event", "operator": "eq", "value": "PageView"}]}}]}}
  }' | jq '{id: .id, name: .name, error: .error.message}'

Note: Replace <PIXEL_ID> with actual pixel ID from Meta Events Manager.

Lookalike Audience (requires origin audience with min 100 matched profiles):

# Prompt for origin audience ID via AskUserQuestion (free text)
curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/customaudiences" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Lookalike — ${ORIGIN_AUDIENCE_NAME} 1%\",
    \"subtype\": \"LOOKALIKE\",
    \"origin_audience_id\": \"${ORIGIN_AUDIENCE_ID}\",
    \"lookalike_spec\": {
      \"country\": \"US\",
      \"ratio\": 0.01,
      \"type\": \"similarity\"
    }
  }" | jq '{id: .id, name: .name, error: .error.message}'

Print: Lookalike audience created (ID: <ID>). Typically takes 1-6 hours to populate.

advantage

Create an Advantage+ Shopping Campaign (AI-optimized).

Collect via AskUserQuestion:

1. Daily budget in dollars (free text)
2. Campaign name (free text)

Then confirm: "Create Advantage+ campaign '<NAME>' with $<BUDGET>/day?" options [Create, Cancel]

BUDGET_CENTS=$(awk "BEGIN {printf \"%d\", ${BUDGET_DOLLARS} * 100}")
curl -s -X POST "https://graph.facebook.com/v20.0/${META_ACCOUNT}/campaigns" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"${CAMPAIGN_NAME}\",
    \"objective\": \"OUTCOME_SALES\",
    \"status\": \"PAUSED\",
    \"special_ad_categories\": [],
    \"daily_budget\": ${BUDGET_CENTS},
    \"smart_promotion_type\": \"AUTOMATED_SHOPPING_ADS\"
  }" | jq '{id: .id, error: .error.message}'

Print: Advantage+ campaign "${CAMPAIGN_NAME}" created (ID: <ID>, status: PAUSED). Meta AI will optimize targeting and creative delivery once enabled.

---

analytics / ga4

Pull GA4 data via the Data API using gcloud ADC.

Get access token

GA4_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)

Sessions + conversions (last 7d)

curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}:runReport" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
    "metrics": [
      {"name": "sessions"},
      {"name": "totalUsers"},
      {"name": "conversions"},
      {"name": "totalRevenue"},
      {"name": "bounceRate"},
      {"name": "averageSessionDuration"}
    ]
  }' | jq '.rows[0].metricValues | {sessions: .[0].value, users: .[1].value, conversions: .[2].value, revenue: .[3].value, bounce_rate: .[4].value}'

Traffic sources (last 7d)

curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}:runReport" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
    "dimensions": [{"name": "sessionDefaultChannelGrouping"}],
    "metrics": [{"name": "sessions"}, {"name": "conversions"}],
    "orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}],
    "limit": 8
  }' | jq '.rows[] | {channel: .dimensionValues[0].value, sessions: .metricValues[0].value, conversions: .metricValues[1].value}'

Top pages (last 7d)

curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}:runReport" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
    "dimensions": [{"name": "pagePath"}],
    "metrics": [{"name": "screenPageViews"}, {"name": "averageSessionDuration"}],
    "orderBys": [{"metric": {"metricName": "screenPageViews"}, "desc": true}],
    "limit": 10
  }' | jq '.rows[] | {page: .dimensionValues[0].value, views: .metricValues[0].value}'

If GA4_TOKEN is empty or gcloud not available, output: GA4 not configured — run /ops:marketing setup or configure gcloud ADC.

Output format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ANALYTICS (GA4) — last 7d
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Sessions:     [N]     Users: [N]
 Conversions:  [N]     CVR:   [X]%
 Revenue:      $[X]
 Bounce Rate:  [X]%    Avg Session: [Xm Xs]

 TRAFFIC SOURCES
 [channel]  [N sessions]  [N conversions]
 ...

 TOP PAGES
 [path]  [N views]

---

ga4-advanced

Advanced GA4 analytics: realtime, funnel, cohort, audience export, and pivot reports.

Credential check: If GA4_TOKEN is empty or GA4_PROPERTY is missing, print GA4 not configured — run /ops:marketing setup or configure gcloud ADC and stop.

Route $ARGUMENTS within ga4-advanced (matches ga4 <sub> pattern):

Input	Action
realtime	Active users right now (last 30 min)
funnel	Conversion funnel with step visualization
cohort	Cohort retention analysis by device
audience	Async audience segment export
pivot	Multi-dimensional pivot report

realtime

GA4_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)
RESULT=$(curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}:runRealtimeReport" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "minuteRanges": [{"startMinutesAgo": 29, "endMinutesAgo": 0}],
    "dimensions": [
      {"name": "unifiedScreenName"},
      {"name": "deviceCategory"}
    ],
    "metrics": [{"name": "activeUsers"}],
    "orderBys": [{"metric": {"metricName": "activeUsers"}, "desc": true}],
    "limit": 10
  }')

TOTAL=$(echo "$RESULT" | jq '[.rows[]?.metricValues[0].value | tonumber] | add // 0')

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  GA4 REALTIME — Last 30 Minutes"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "Active Users Right Now: ${TOTAL}"
echo ""
echo "Top Pages:"
printf "| %-40s | %-8s | %-7s |\n" "Page" "Device" "Users"
printf "|%s|%s|%s|\n" "------------------------------------------" "----------" "---------"
echo "$RESULT" | jq -r '.rows[]? | [.dimensionValues[0].value, .dimensionValues[1].value, .metricValues[0].value] | @tsv' 2>/dev/null | \
  while IFS=$'\t' read -r page device users; do
    printf "| %-40s | %-8s | %-7s |\n" "${page:0:40}" "$device" "$users"
  done

funnel

Ask user for funnel steps via AskUserQuestion (free text). Default template uses session_start → page_view → purchase.

# NOTE: Uses v1alpha — breaking changes possible per Google's versioning policy
GA4_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)

# Prompt for funnel type first
# AskUserQuestion: "Funnel mode?" options [Closed funnel, Open funnel]

IS_OPEN=$([ "$FUNNEL_MODE" = "Open funnel" ] && echo "true" || echo "false")

RESULT=$(curl -s -X POST "https://analyticsdata.googleapis.com/v1alpha/properties/${GA4_PROPERTY}:runFunnelReport" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"dateRanges\": [{\"startDate\": \"30daysAgo\", \"endDate\": \"today\"}],
    \"funnel\": {
      \"isOpenFunnel\": ${IS_OPEN},
      \"steps\": [
        {
          \"name\": \"Session Start\",
          \"filterExpression\": {\"funnelEventFilter\": {\"eventName\": \"session_start\"}}
        },
        {
          \"name\": \"Page View\",
          \"filterExpression\": {\"funnelEventFilter\": {\"eventName\": \"page_view\"}}
        },
        {
          \"name\": \"Purchase\",
          \"filterExpression\": {\"funnelEventFilter\": {\"eventName\": \"purchase\"}}
        }
      ]
    },
    \"funnelBreakdown\": {
      \"breakdownDimension\": {\"name\": \"deviceCategory\"},
      \"limit\": 4
    }
  }")

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  GA4 FUNNEL — Last 30 Days (${FUNNEL_MODE})"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "$RESULT" | jq -r '
  .funnelTable.rows[]? |
  "Step: \(.dimensionValues[0].value)  Users: \(.metricValues[0].value)  Completion: \(.metricValues[1].value)%  Abandoned: \(.metricValues[2].value)"
' 2>/dev/null || echo "No funnel data — ensure purchase events are firing in GA4."

cohort

Weekly cohort retention for users acquired in the past month, broken down by device.

GA4_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)
START_DATE=$(date -v-30d +%Y-%m-%d 2>/dev/null || date -d '30 days ago' +%Y-%m-%d)
END_DATE=$(date +%Y-%m-%d)

RESULT=$(curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}:runReport" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"dimensions\": [
      {\"name\": \"cohort\"},
      {\"name\": \"cohortNthWeek\"},
      {\"name\": \"deviceCategory\"}
    ],
    \"metrics\": [
      {\"name\": \"cohortActiveUsers\"},
      {\"name\": \"cohortRetentionFraction\"}
    ],
    \"cohortSpec\": {
      \"cohorts\": [{
        \"dimension\": \"firstSessionDate\",
        \"dateRange\": {\"startDate\": \"${START_DATE}\", \"endDate\": \"${END_DATE}\"}
      }],
      \"cohortsRange\": {
        \"granularity\": \"WEEKLY\",
        \"startOffset\": 0,
        \"endOffset\": 5
      }
    }
  }")

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  GA4 COHORT RETENTION — Last 30 Days"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
printf "| %-12s | %-6s | %-8s | %-10s | %-10s |\n" "Cohort" "Week" "Device" "Users" "Retention%"
printf "|%s|%s|%s|%s|%s|\n" "--------------" "--------" "----------" "------------" "------------"
echo "$RESULT" | jq -r '.rows[]? | [
  .dimensionValues[0].value,
  .dimensionValues[1].value,
  .dimensionValues[2].value,
  .metricValues[0].value,
  (.metricValues[1].value | tonumber * 100 | tostring | split(".")[0])
] | @tsv' 2>/dev/null | \
  while IFS=$'\t' read -r cohort week device users retention; do
    printf "| %-12s | %-6s | %-8s | %-10s | %-10s |\n" "$cohort" "$week" "$device" "$users" "${retention}%"
  done

audience

Async audience export: create → poll until ACTIVE → show user count.

GA4_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)

# Step 1: List available audiences so user can pick one
AUDIENCES=$(curl -s "https://analyticsadmin.googleapis.com/v1alpha/properties/${GA4_PROPERTY}/audiences" \
  -H "Authorization: Bearer ${GA4_TOKEN}")
echo "Available audiences:"
echo "$AUDIENCES" | jq -r '.audiences[]? | "\(.name | split("/") | last): \(.displayName)"' 2>/dev/null

# AskUserQuestion: "Enter audience ID from list above:" (free text)

# Step 2: Create export
EXPORT_RESP=$(curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}/audienceExports" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"audience\": \"properties/${GA4_PROPERTY}/audiences/${AUDIENCE_ID}\",
    \"dimensions\": [
      {\"dimensionName\": \"deviceId\"},
      {\"dimensionName\": \"isAdsPersonalizationAllowed\"}
    ]
  }")
EXPORT_NAME=$(echo "$EXPORT_RESP" | jq -r '.name // empty')

if [ -z "$EXPORT_NAME" ]; then
  echo "Failed to create export: $(echo "$EXPORT_RESP" | jq -r '.error.message // "unknown error"')"
  exit 0
fi

echo "Export created: ${EXPORT_NAME}"
echo "Polling for completion (small audiences: ~30s, large: up to 15 min)..."

# Step 3: Poll until ACTIVE or FAILED
ATTEMPTS=0
while [ $ATTEMPTS -lt 60 ]; do
  STATUS_RESP=$(curl -s "https://analyticsdata.googleapis.com/v1beta/${EXPORT_NAME}" \
    -H "Authorization: Bearer ${GA4_TOKEN}")
  STATE=$(echo "$STATUS_RESP" | jq -r '.state // "UNKNOWN"')
  PCT=$(echo "$STATUS_RESP" | jq -r '.percentageCompleted // 0')

  if [ "$STATE" = "ACTIVE" ]; then break; fi
  if [ "$STATE" = "FAILED" ]; then
    echo "Export failed. Try again or check GA4 audience configuration."
    exit 0
  fi
  echo "  State: ${STATE} (${PCT}% complete)..."
  sleep 10
  ATTEMPTS=$((ATTEMPTS + 1))
done

# Step 4: Query results
QUERY_RESP=$(curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/${EXPORT_NAME}:query" \
  -H "Authorization: Bearer ${GA4_TOKEN}")
ROW_COUNT=$(echo "$QUERY_RESP" | jq '.rowCount // 0')

echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  GA4 AUDIENCE EXPORT"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  Audience ID: ${AUDIENCE_ID}"
echo "  Users exported: ${ROW_COUNT}"
echo "  Ads-eligible: $(echo "$QUERY_RESP" | jq '[.audienceRows[]? | select(.dimensionValues[1].value == "true")] | length') users"
echo ""
echo "Export ready. Use this audience for retargeting in Meta or Google Ads."

pivot

Multi-dimensional pivot: channel group × device category × conversions.

GA4_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)

RESULT=$(curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY}:runPivotReport" \
  -H "Authorization: Bearer ${GA4_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [
      {"name": "sessionDefaultChannelGrouping"},
      {"name": "deviceCategory"}
    ],
    "metrics": [
      {"name": "sessions"},
      {"name": "conversions"},
      {"name": "totalRevenue"}
    ],
    "pivots": [
      {
        "fieldNames": ["sessionDefaultChannelGrouping"],
        "limit": 6
      },
      {
        "fieldNames": ["deviceCategory"],
        "limit": 3
      }
    ]
  }')

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  GA4 PIVOT — Channel × Device (Last 30 Days)"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
printf "| %-20s | %-8s | %-10s | %-11s | %-10s |\n" "Channel" "Device" "Sessions" "Conversions" "Revenue"
printf "|%s|%s|%s|%s|%s|\n" "----------------------" "----------" "------------" "-------------" "------------"
echo "$RESULT" | jq -r '.rows[]? | [
  .dimensionValues[0].value,
  .dimensionValues[1].value,
  .metricValues[0].value,
  .metricValues[1].value,
  (.metricValues[2].value | tonumber | . * 100 | round / 100 | tostring)
] | @tsv' 2>/dev/null | \
  while IFS=$'\t' read -r channel device sessions convs revenue; do
    printf "| %-20s | %-8s | %-10s | %-11s | \$%-9s |\n" "${channel:0:20}" "$device" "$sessions" "$convs" "$revenue"
  done

---

seo / gsc

Pull Google Search Console data.

Get access token (same gcloud ADC)

GSC_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)
GSC_SITE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('${GSC_SITE}', safe=''))" 2>/dev/null || echo "${GSC_SITE}" | sed 's|:|%3A|g; s|/|%2F|g')

Search performance (last 28 days)

curl -s -X POST "https://searchconsole.googleapis.com/webmasters/v3/sites/${GSC_SITE_ENCODED}/searchAnalytics/query" \
  -H "Authorization: Bearer ${GSC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "'$(date -v-28d +%Y-%m-%d 2>/dev/null || date -d '28 days ago' +%Y-%m-%d)'",
    "endDate": "'$(date +%Y-%m-%d)'",
    "dimensions": [],
    "rowLimit": 1
  }' | jq '{clicks: .rows[0].clicks, impressions: .rows[0].impressions, ctr: .rows[0].ctr, position: .rows[0].position}'

Top queries (last 28 days)

curl -s -X POST "https://searchconsole.googleapis.com/webmasters/v3/sites/${GSC_SITE_ENCODED}/searchAnalytics/query" \
  -H "Authorization: Bearer ${GSC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "'$(date -v-28d +%Y-%m-%d 2>/dev/null || date -d '28 days ago' +%Y-%m-%d)'",
    "endDate": "'$(date +%Y-%m-%d)'",
    "dimensions": ["query"],
    "rowLimit": 20,
    "dimensionFilterGroups": []
  }' | jq '.rows[] | {query: .keys[0], clicks: .clicks, impressions: .impressions, position: (.position | floor)}'

Top pages by clicks

curl -s -X POST "https://searchconsole.googleapis.com/webmasters/v3/sites/${GSC_SITE_ENCODED}/searchAnalytics/query" \
  -H "Authorization: Bearer ${GSC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "'$(date -v-28d +%Y-%m-%d 2>/dev/null || date -d '28 days ago' +%Y-%m-%d)'",
    "endDate": "'$(date +%Y-%m-%d)'",
    "dimensions": ["page"],
    "rowLimit": 10
  }' | jq '.rows[] | {page: .keys[0], clicks: .clicks, impressions: .impressions, position: (.position | floor)}'

If GSC not configured, output: Search Console not configured — run /ops:marketing setup.

Output format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SEO (SEARCH CONSOLE) — last 28d
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Clicks:       [N]
 Impressions:  [N]
 CTR:          [X]%
 Avg Position: [X]

 TOP QUERIES
 [query]  [clicks] clicks  pos [N]
 ...

 TOP PAGES
 [url]  [clicks] clicks  [impressions] impr

---

social

Aggregate available social media metrics. Check which are configured.

Instagram (via Meta Graph API — same token as Meta Ads)

# Get Instagram Business Account ID linked to the ad account
curl -s "https://graph.facebook.com/v18.0/me/accounts?fields=instagram_business_account" \
  -H "Authorization: Bearer ${META_TOKEN}" | jq '.data[].instagram_business_account.id' 2>/dev/null

# Then pull media insights
curl -s "https://graph.facebook.com/v18.0/${IG_ACCOUNT_ID}?fields=followers_count,media_count,profile_views" \
  -H "Authorization: Bearer ${META_TOKEN}" | jq '{followers: .followers_count, posts: .media_count, profile_views: .profile_views}'

YouTube (if configured via gcloud)

YT_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)
curl -s "https://www.googleapis.com/youtube/v3/channels?part=statistics&mine=true" \
  -H "Authorization: Bearer ${YT_TOKEN}" | jq '.items[0].statistics | {subscribers: .subscriberCount, views: .viewCount, videos: .videoCount}'

Show [not configured] for any unconfigured channels rather than failing.

Output format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SOCIAL MEDIA
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Instagram:  [N followers]  [N posts]  [N profile views]
 YouTube:    [N subscribers]  [N total views]
 TikTok:     [not configured] — set TIKTOK_ACCESS_TOKEN

---

instagram

Instagram publishing and insights via Instagram Graph API (same META_TOKEN as Meta Ads).

Prerequisites:

• META_TOKEN configured (same as Meta Ads)
• Instagram Business account linked to a Facebook Page
• IG_ACCOUNT_ID resolved via: curl "https://graph.facebook.com/v21.0/me/accounts?fields=instagram_business_account" -H "Authorization: Bearer ${META_TOKEN}" → data[0].instagram_business_account.id

Rate limit: 200 API calls/hour per app. Demographics require 48h reporting delay. Media insights require account with >1,000 followers.

Resolve IG account ID at the start of every instagram invocation:

IG_ACCOUNT_ID=$(claude plugin config get instagram_account_id 2>/dev/null)
if [ -z "$IG_ACCOUNT_ID" ]; then
  IG_ACCOUNT_ID=$(curl -s "https://graph.facebook.com/v21.0/me/accounts?fields=instagram_business_account" \
    -H "Authorization: Bearer ${META_TOKEN}" | jq -r '.data[0].instagram_business_account.id // empty')
  # Cache it
  [ -n "$IG_ACCOUNT_ID" ] && claude plugin config set instagram_account_id "$IG_ACCOUNT_ID" 2>/dev/null
fi
if [ -z "$IG_ACCOUNT_ID" ]; then
  echo "Instagram Business account not linked to your Meta token. Ensure your Facebook Page has an Instagram Business account connected."
  exit 0
fi

Route $ARGUMENTS within instagram:

Input	Action
post <IMAGE_URL>	Publish image post to feed
reel <VIDEO_URL>	Publish a Reel
story <IMAGE_URL|VIDEO_URL>	Publish a Story
insights <MEDIA_ID>	Per-post metrics
account-insights [days]	Account-level reach + impressions
demographics	Audience age/gender/location

post

Publish an image post (two-step: create container → publish).

Collect via AskUserQuestion:

1. Image URL (publicly accessible HTTPS URL) — free text
2. Caption — free text

# Step 1: Create media container
CONTAINER=$(curl -s -X POST "https://graph.facebook.com/v21.0/${IG_ACCOUNT_ID}/media" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "image_url=${IMAGE_URL}" \
  -F "caption=${CAPTION}" \
  -F "media_type=IMAGE")
CONTAINER_ID=$(echo "$CONTAINER" | jq -r '.id // empty')

if [ -z "$CONTAINER_ID" ]; then
  echo "Failed to create media container: $(echo "$CONTAINER" | jq -r '.error.message // "unknown error"')"
  exit 0
fi

# Step 2: Publish
PUBLISH=$(curl -s -X POST "https://graph.facebook.com/v21.0/${IG_ACCOUNT_ID}/media_publish" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "creation_id=${CONTAINER_ID}")
MEDIA_ID=$(echo "$PUBLISH" | jq -r '.id // empty')

if [ -n "$MEDIA_ID" ]; then
  echo "Post published (Media ID: ${MEDIA_ID}). View at https://www.instagram.com/ — may take 1-2 min to appear."
else
  echo "Publish failed: $(echo "$PUBLISH" | jq -r '.error.message // "unknown error"')"
fi

reel

Publish a Reel. Video must be an HTTPS URL (MP4, H.264, max 15 min, min 500px width).

Collect via AskUserQuestion:

1. Video URL (HTTPS) — free text
2. Caption — free text

# Step 1: Create video container (async — must poll for status)
CONTAINER=$(curl -s -X POST "https://graph.facebook.com/v21.0/${IG_ACCOUNT_ID}/media" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "media_type=REELS" \
  -F "video_url=${VIDEO_URL}" \
  -F "caption=${CAPTION}" \
  -F "share_to_feed=true")
CONTAINER_ID=$(echo "$CONTAINER" | jq -r '.id // empty')

if [ -z "$CONTAINER_ID" ]; then
  echo "Failed to create Reel container: $(echo "$CONTAINER" | jq -r '.error.message // "unknown error"')"
  exit 0
fi

echo "Reel uploading... polling for ready status."

# Poll until status is FINISHED
ATTEMPTS=0
while [ $ATTEMPTS -lt 30 ]; do
  STATUS=$(curl -s "https://graph.facebook.com/v21.0/${CONTAINER_ID}?fields=status_code" \
    -H "Authorization: Bearer ${META_TOKEN}" | jq -r '.status_code // "UNKNOWN"')
  [ "$STATUS" = "FINISHED" ] && break
  [ "$STATUS" = "ERROR" ] && echo "Reel processing failed." && exit 0
  sleep 10
  ATTEMPTS=$((ATTEMPTS + 1))
done

# Step 2: Publish
PUBLISH=$(curl -s -X POST "https://graph.facebook.com/v21.0/${IG_ACCOUNT_ID}/media_publish" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "creation_id=${CONTAINER_ID}")
MEDIA_ID=$(echo "$PUBLISH" | jq -r '.id // empty')

if [ -n "$MEDIA_ID" ]; then
  echo "Reel published (Media ID: ${MEDIA_ID}). Reach and plays metrics available after 24-48h."
else
  echo "Reel publish failed: $(echo "$PUBLISH" | jq -r '.error.message // "unknown error"')"
fi

story

Publish a Story (image or video, 24h expiry).

Collect via AskUserQuestion:

1. Content URL (HTTPS image or video) — free text
2. Content type: [Image story, Video story]

if [ "$CONTENT_TYPE" = "Video story" ]; then
  MEDIA_TYPE="VIDEO"
  URL_FIELD="video_url"
else
  MEDIA_TYPE="IMAGE"
  URL_FIELD="image_url"
fi

CONTAINER=$(curl -s -X POST "https://graph.facebook.com/v21.0/${IG_ACCOUNT_ID}/media" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "media_type=STORIES" \
  -F "${URL_FIELD}=${CONTENT_URL}")
CONTAINER_ID=$(echo "$CONTAINER" | jq -r '.id // empty')

if [ -z "$CONTAINER_ID" ]; then
  echo "Failed to create Story container: $(echo "$CONTAINER" | jq -r '.error.message // "unknown error"')"
  exit 0
fi

PUBLISH=$(curl -s -X POST "https://graph.facebook.com/v21.0/${IG_ACCOUNT_ID}/media_publish" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -F "creation_id=${CONTAINER_ID}")
MEDIA_ID=$(echo "$PUBLISH" | jq -r '.id // empty')

if [ -n "$MEDIA_ID" ]; then
  echo "Story published (Media ID: ${MEDIA_ID}). Expires after 24 hours."
else
  echo "Story publish failed: $(echo "$PUBLISH" | jq -r '.error.message // "unknown error"')"
fi

insights <MEDIA_ID>

Per-post metrics. Note: reach, saves, shares deprecated for non-Reels video; plays only for Reels/video.

METRICS="reach,saved,shares,comments_count,like_count,impressions"
# For Reels, add plays: detect via media_type field
MEDIA_TYPE=$(curl -s "https://graph.facebook.com/v21.0/${MEDIA_ID}?fields=media_type" \
  -H "Authorization: Bearer ${META_TOKEN}" | jq -r '.media_type // "IMAGE"')