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, session inspection, and organization management. Everything you do in Hellyeah (campaigns, wallet, brand profile, trackers) belongs to your organization, shared with any teammates you invite.

• 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 auth org list: Show the active organization and all memberships
• hellyeah auth org set <org-id>: Set the active organization for tenant-scoped commands
• hellyeah auth org clear: Clear the active organization selector
• hellyeah auth org invite <email> --yes: Invite a teammate to the active organization
• hellyeah auth org leave --yes: Leave the active organization
• hellyeah auth org rename <name> [--slug <slug>] --yes: Rename the active organization (owners only); the slug is derived from the name unless --slug is passed
• 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. Completing your profile for the first time also names your organization after your business and sets your brand logo as its avatar; owners can rename it later with auth org rename.

• 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 committed campaign budgets

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> --reference <id> [--novelty <0-1>] [--size landscape|square|all]: Reference-led 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

Fund, submit, inspect, and control a paid ad campaign.

• hellyeah campaign launch --name <str> --text-id <id> [--image-id <id> ...] --budget <usd> [--budget-type total] --end-date <date> --keyword <kw> --location <loc> [--idempotency-key <key>] --yes: Debit the lifetime budget and submit for internal review; reuse the key only to continue an ambiguous attempt
• 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>]: Withdraw or cancel; pre-platform requests refund immediately, platform-backed campaigns settle first

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

{
  "success": true,
  "requestId": "7c2d0a1a-6bd6-4d90-a1b3-0a5b6e51f6c2",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "status": "pending_internal_review",
    "funded": true,
    "creativeDraftId": "550e8400-e29b-41d4-a716-446655440000",
    "calendarWindow": {
      "deliveryStartDate": "2026-07-17",
      "deliveryEndDate": "2026-08-31",
      "calendarEndDate": "2026-09-02",
      "bufferDays": 2,
      "activeDeliveryDays": 46,
      "isHardDeadline": false
    },
    "message": "Campaign submitted for review"
  }
}

Tracker

Provision, inspect, update, and verify the org's X-Ray tracker.

• hellyeah tracker create (--domain <str> | --pre-launch) [--name <str>] [--org <uuid>] --json: Create or return the org tracker
• hellyeah tracker state [--org <uuid>] --json: Inspect the org tracker and recent delivery state
• hellyeah tracker update --domain <str> [--org <uuid>] --json: Update the org tracker's domain
• hellyeah tracker verify [--org <uuid>] [--env <str>] --json: Poll for recent tracker delivery

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

{
  "success": true,
  "data": {
    "trackerId": "00000000-0000-4000-8000-000000000000",
    "domain": "acme.com",
    "domainPlaceholder": false,
    "code": "ok",
    "nextAction": "Run `hellyeah tracker verify --json`.",
    "exportCommand": "export HELLYEAH_TRACKER_ID=00000000-0000-4000-8000-000000000000"
  }
}

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, opencode, universal)
• hellyeah skills add <name> --global: Install into the user-global skill location
• hellyeah skills add <name> --yes: Accept detected targets without prompting
• hellyeah skills add <name> --copy: Copy files instead of symlinking

Example: hellyeah skills add hellyeah --global --yes --json

{
  "success": true,
  "data": {
    "skill": "hellyeah",
    "agentResolution": "standard",
    "installed": [
      {
        "agent": "universal",
        "path": "~/.agents/skills/hellyeah",
        "mode": "symlink",
        "scope": "global",
        "action": "installed"
      }
    ],
    "updated": [],
    "overwritten": [],
    "upToDate": [],
    "skipped": [],
    "failed": [],
    "summary": {
      "installed": 1,
      "updated": 0,
      "overwritten": 0,
      "upToDate": 0,
      "skipped": 0,
      "failed": 0,
      "completed": true
    }
  }
}

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.