Command reference

Every Hellyeah CLI command, grouped by surface. One line per command. For deep dives, see Concepts and Launch your first ad.

Each group lists its commands, then an Example showing what --json returns. The shape under data is what coding agents should parse. The full envelope is documented in Output contract.

Auth

Browser-based login, credential storage, and session inspection.

• hellyeah auth login: Browser-based Hellyeah login
• hellyeah auth logout: Clear stored credentials for the current API/auth context
• hellyeah auth whoami: Current user and org as JSON
• hellyeah config status: Show resolved config and credential state

Example: hellyeah auth whoami --json

{
  "success": true,
  "requestId": "7c2d0a1a-6bd6-4d90-a1b3-0a5b6e51f6c2",
  "data": {
    "userId": "user_2nQz9bL3kAxR0fGh",
    "email": "you@acme.com",
    "orgId": "org_2nR0c8Ld4ByS1gHi",
    "orgName": "Acme Inc.",
    "scope": "production"
  }
}

Profile

Manage the brand profile every campaign and creative anchors to.

• hellyeah profile get: Current brand profile (JSON, includes isComplete)
• hellyeah profile update: Create or update fields (--business-name, --website-url, --industry, --description, --target-audience, --tone, --value-proposition, --main-goal, optional --brand-colors, --logos)

Example: hellyeah profile get --json

{
  "success": true,
  "data": {
    "businessName": "Acme",
    "websiteUrl": "https://acme.com",
    "industry": "saas",
    "description": "Acme helps small teams ship faster.",
    "targetAudience": "engineering managers at 10-50 person startups",
    "tone": "direct, helpful",
    "isComplete": true
  }
}

Wallet

Prepaid balance that funds campaigns. Check it, top it up, audit it.

• hellyeah wallet balance: Current balance in USD (cents on the wire)
• hellyeah wallet topup --amount <usd>: Opens Stripe Checkout, polls until paid (5 min timeout)
• hellyeah wallet topup --amount <usd> --checkout-only: Return the Checkout URL without opening a browser
• hellyeah wallet transactions: Recent transaction history (--limit, --since)
• hellyeah wallet reservations: Outstanding holds against active campaigns

Example: hellyeah wallet balance --json

{
  "success": true,
  "data": {
    "balanceCents": 12500,
    "balanceUsd": "125.00",
    "currency": "USD",
    "reservedCents": 5000,
    "availableCents": 7500
  }
}

Billing

Refund status for canceled or failed campaign reservations.

• hellyeah billing refunds: Refund history, optionally scoped with --campaign <id>

Example: hellyeah billing refunds --json

{
  "success": true,
  "data": {
    "refunds": [
      {
        "id": "rfd_2nR4xY7mN2pQ0sJk",
        "campaignId": "cmp_2nR1aB3cD5eF6gH",
        "amountCents": 2500,
        "reason": "campaign_cancelled",
        "status": "settled",
        "createdAt": "2026-05-08T18:14:22Z"
      }
    ],
    "nextCursor": null
  }
}

Creative

Generate profile-locked ad copy and images.

• hellyeah creative generate text --hook <hook> [--tone <tone>] [--audience <str>] [--campaign <str>]: Sync ad copy generation
• hellyeah creative generate image --hook <hook> [--novelty <0-1>] [--size landscape|square|all]: Async image generation (returns jobId)
• hellyeah creative status --job-id <id> [--watch]: Poll a creative job
• hellyeah creative list [--status <s>] [--kind text|image] [--limit <n>]: Recent CLI-originated jobs

Example: hellyeah creative generate text --hook problem_solution --json

{
  "success": true,
  "data": {
    "creativeId": "crt_2nR5dE6fG7hI8jK",
    "kind": "text",
    "headlines": [
      "Ship Paid Ads From Your Editor",
      "Your Agent. Your Ads. Live in Minutes.",
      "Stop Context-Switching for Marketing"
    ],
    "descriptions": [
      "Install the CLI. Your coding agent launches Google Ads."
    ],
    "lockedProfile": "Acme"
  }
}

Campaign

Launch, list, get, pause, resume, cancel: the six commands that manage a paid ad campaign.

• hellyeah campaign launch --name <str> --text-id <id> [--image-id <id> ...] --budget <usd> --budget-type daily|total --keyword <kw> --location <loc> --yes: Atomic launch
• hellyeah campaign list [--status <s>] [--platform <p>] [--limit <n>] [--cursor <c>]: All campaigns
• hellyeah campaign get <id>: Full campaign detail with next-action hint
• hellyeah campaign status <id> [--daily]: Status + cached performance metrics
• hellyeah campaign pause <id>: Pause an active campaign
• hellyeah campaign resume <id>: Resume a paused campaign
• hellyeah campaign cancel <id> --yes [--reason <str>]: Cancel; refund scheduled 48h later

Example: hellyeah campaign launch --name "Acme Q2" ... --yes --json

{
  "success": true,
  "data": {
    "campaignId": "cmp_2nR1aB3cD5eF6gH",
    "name": "Acme Q2",
    "platform": "google",
    "status": "launching",
    "budgetCents": 50000,
    "budgetType": "daily",
    "reservationCents": 50000,
    "next": ["hellyeah campaign status cmp_2nR1aB3cD5eF6gH"]
  }
}

Tracker

Provision X-Ray trackers and bind one to the current project.

• hellyeah tracker create --domain <str> [--name <str>] [--org <uuid>] --yes: Provision a tracker
• hellyeah tracker list [--limit <n>] [--cursor <uuid>] [--org <uuid>]: List trackers
• hellyeah tracker get <id>: One tracker
• hellyeah tracker link <id> [--force] [--cwd <path>]: Bind tracker to this project (writes ./.hellyeah/config.json)
• hellyeah tracker unlink [--cwd <path>]: Remove the project's tracker binding
• hellyeah tracker install: Install the tracker skill and launch a coding agent to wire the snippet

Example: hellyeah tracker create --domain acme.com --yes --json

{
  "success": true,
  "data": {
    "trackerId": "trk_2nR6gH7iJ8kL9mN",
    "websiteId": "wbs_2nR6gH7iJ8kL9mN",
    "domain": "acme.com",
    "scriptUrl": "https://xray.hellyeahai.com/script.js",
    "snippet": "<script defer src=\"https://xray.hellyeahai.com/script.js\" data-website-id=\"wbs_2nR6gH7iJ8kL9mN\"></script>",
    "next": ["hellyeah tracker link trk_2nR6gH7iJ8kL9mN"]
  }
}

Skills

Install Hellyeah agent skills into your coding agent's local skill directory.

• hellyeah skills list: Available skills with one-line descriptions
• hellyeah skills add <name>: Install a skill (e.g. hellyeah, tracker)
• hellyeah skills add <name> --agent <agent>: Target a specific agent (claude-code, cursor, codex, universal)
• hellyeah skills add <name> --global: Install into the user-global skill location
• hellyeah skills add <name> --copy: Copy files instead of symlinking

Example: hellyeah skills add hellyeah --json

{
  "success": true,
  "data": {
    "skill": "hellyeah",
    "agent": "claude-code",
    "installedAt": "~/.agents/skills/hellyeah",
    "mode": "symlink",
    "next": ["restart your coding agent so it picks up the new skill"]
  }
}

Feedback

One sink for human notes and structured agent reports: crashes, suggestions, friction.

• hellyeah feedback "message": Quick human note (kind: "note")
• cmd | hellyeah feedback: Agent invocation. Structured JSON payload from stdin (kind: note|crash|suggestion)

Example: hellyeah feedback "creative gen felt slow today" --json

{
  "success": true,
  "data": {
    "feedbackId": "fbk_2nR8mN9pQ0rS1tU",
    "kind": "note",
    "accepted": true
  }
}

Output contract

The wire-level agreement every command obeys.

JSON envelope (success):

{
  "success": true,
  "requestId": "7c2d0a1a-6bd6-4d90-a1b3-0a5b6e51f6c2",
  "data": { "...": "command-specific payload" }
}

JSON envelope (error):

{
  "success": false,
  "requestId": "7c2d0a1a-6bd6-4d90-a1b3-0a5b6e51f6c2",
  "error": {
    "code": "insufficient_balance",
    "message": "Wallet balance is $12.50, need $50.00 to launch.",
    "next": ["hellyeah wallet topup --amount 50"]
  }
}

error.code is stable and agent-safe. error.message is free to change between releases. error.next is best-effort guidance: an array of suggested follow-up commands an agent can run (with user consent) to recover.

Exit codes:

Authentication. Commands use the account from hellyeah auth login by default. For server-side automation, pass an API key with --api-key or HELLYEAH_API_KEY.

Money types. Every money field on the wire is an integer count of USD cents (balance_cents, amount_cents, reservation_cents). The CLI converts to USD strings at the human boundary. No float math anywhere in the path.

Format selection. Use --json (or --format json) for the machine contract. The default human format at a TTY shows tables and one-line summaries. JSON envelopes go to stdout; spinners and hints go to stderr.