# Changelog (/changelog)



Notable changes to the [Hellyeah CLI](/cli) (`hellyeah` on npm).

The format follows [Keep a Changelog](https://keepachangelog.com), and the CLI follows [Semantic Versioning](https://semver.org). The [X-Ray SDK](/tracking) ships continuously and isn't versioned here.

## \[1.2.0] - 2026-06-30 [#120---2026-06-30]

Research and creative release. Point the CLI at a URL to build your brand profile, generate a finished ad in one command, and launch worldwide without fighting location flags.

### Added [#added]

* `hellyeah profile research <url>`: auto-fill your brand profile from a website. It proposes a name, description, colors (each hex shown with a swatch), and logo. In a terminal it loops: `y` applies, `n` skips, and any other text is a plain-language instruction to revise the proposal for another round. `--yes` and `--json` run it unattended.
* Bare URL shortcut: `hellyeah <url>` goes straight to profile research.
* `hellyeah stripe`: connect your own Stripe account via Stripe Connect so revenue from your campaigns is tracked back to them (`connect`, `status`, `disconnect`).
* `hellyeah creative workflow`: one command runs the creative wizard, then generates the image, the text, and the blended ad together. Pass `--hook` and `--headline` to run it non-interactively for agents, no terminal needed.
* Position and font controls when editing creative text, plus an edit-blend command.

### Changed [#changed]

* `--location` is now optional on `campaign launch`. Omit it to serve worldwide (Google's default). "Worldwide", "Global", and similar terms now resolve to no geographic restriction instead of being matched to the wrong place.

### Fixed [#fixed]

* Blank or whitespace-only `--location`, `--keyword`, and `--language` values are rejected before launch (with a hint to omit the flag for worldwide) instead of being sent to Google as a real target.
* `creative generate text --rsa` descriptions respect Google's 90-character limit as they are written, so a description is no longer cut mid-phrase or left with a dangling comma.

### Beyond the CLI [#beyond-the-cli]

Shipped alongside this release on the continuous (unversioned) track:

* **Customer dashboard.** A web view of your campaigns, spend, and website analytics (traffic breakdown, sessions over time, and events) in one place. Campaign cards show creative previews and your brand logo, with timestamps in your local timezone.
* **Performance Max, end to end.** Performance Max campaigns run with full creation, sync, policy checks, and reporting, including worldwide (no-location) PMax.
* **Sharper creatives.** Generated ad images render text at exact ad dimensions with a cleaner two-layer compositor, and ad copy stays within Google's limits.

## \[1.1.0] - 2026-06-12 [#110---2026-06-12]

Visibility release. Money, refunds, environments, and campaign states now explain themselves, and launches can be fully validated before a dollar moves.

### Added [#added-1]

* `hellyeah doctor`: one-command diagnostic covering environment, API reachability, credentials, and the binary you're actually running (path, install method, channel, version), with a copy-pasteable line for bug reports.
* `campaign launch --dry-run` now validates every launch requirement at once (ad account, creatives, budget, spend caps, and wallet balance) and reports all blockers together with exact top-up math. Exit 0 means the campaign is launchable. Read-only, no confirmation needed.
* Organization awareness in money commands: wallet, campaign launch/cancel, and billing print which organization they act on, and warn before the first risky command when you belong to several organizations.
* Campaigns tell you what you can do next: `campaign get` and `status` list the actions available right now (pause / resume / cancel), and a blocked action explains what is available instead.
* Refund visibility end to end: `campaign cancel` shows the refund amount and when it credits back; `wallet balance` and `wallet transactions` show refunds on the way; `campaign get` and `list` separate money still held from refunds pending; `billing refunds` explains an empty list instead of "No refunds found."
* `creative generate text --rsa`: Google Search headlines written as complete standalone phrases.
* Pre-launch tracker mode: `tracker create` works before your domain is live, so tracking can be installed ahead of launch.
* `auth org rename`, and `profile update` keeps your organization name in sync with your brand profile.
* `skills update` and `skills remove`, and `skills add` auto-detects which AI agent it's running in.
* `hellyeah feedback` scrubs secrets before anything leaves your machine: environment values, common API key patterns, and credentials in URLs are redacted client-side.
* Campaign list shows the failure reason on failed campaigns.

### Fixed [#fixed-1]

* Promo codes now apply at wallet top-up checkout.
* Login is reliable on headless machines, and network errors are reported distinctly from API errors.
* Creative generation no longer requires saved brand colors, and generated images carry your actual logo.
* `hellyeah help` works, and running with no arguments prints useful guidance.

## \[1.0.0] - 2026-06-05 [#100---2026-06-05]

First public release of the CLI on npm. Install once, then run bare `hellyeah`.

### Added [#added-2]

* Native installer for macOS, Linux, and Windows (`curl -fsSL https://hellyeah.sh | sh`), with npm and npx as alternatives for Node environments. `npx hellyeah install` puts the binary on your PATH.
* `hellyeah auth`: browser-based `login`, `logout`, and `whoami`, plus organization management with `auth org` (`list`, `set`, `clear`, `invite`, `leave`).
* `hellyeah config status`: resolved config and credential state.
* `hellyeah profile`: research and save the brand profile every campaign and creative anchors to (`get`, `update`).
* `hellyeah wallet`: prepaid balance that funds campaigns (`balance`, `topup` via Stripe Checkout, `transactions`, `reservations`).
* `hellyeah billing refunds`: refund status for canceled or failed campaign reservations.
* `hellyeah creative`: generate brand-locked ad copy and images (`generate text` sync, `generate image` async, `status`, `list`).
* `hellyeah campaign`: full lifecycle (`launch`, `list`, `get`, `status`, `pause`, `resume`, `cancel`).
* `hellyeah tracker`: provision and link [X-Ray](/tracking) trackers (`create`, `list`, `get`, `link`, `unlink`, `install`).
* `hellyeah skills`: install Hellyeah agent skills into Claude Code, Cursor, Codex, and others (`list`, `add`).
* `hellyeah feedback`: one sink for human notes and structured agent reports.
* A structured output contract. Every command returns a JSON envelope under `--json`, with stable `error.code`s, `next`-action hints for agents, and documented exit codes. Every money field is an integer count of USD cents on the wire.
* Approval gates on money movement. Wallet top-ups and campaign launches always pause for an explicit human "yes". The agent never moves dollars on its own.

### Known limitations [#known-limitations]

* **Google Ads only** (search and Performance Max). Meta Ads, TikTok Ads, and multi-channel attribution are on the roadmap, not in this release.
* **Managed accounts only.** Campaigns run on a pool of Google Ads accounts that Hellyeah owns. Bring-your-own-account is not supported yet.

See the [FAQ](/faq) for more on what is and isn't supported today.


---

# FAQ (/faq)



## What does Hellyeah do? [#what-does-hellyeah-do]

Hellyeah ships paid ads for AI-built apps. There are two ways to drive it:

* **Developers** use the [Hellyeah CLI](/cli) from their coding agent (Claude Code, Cursor, Codex, Replit Agent, Windsurf, v0) to run Google Ads. Add the [X-Ray Tracking SDK](/tracking) to send app events and conversions back into Hellyeah.
* **Business owners** use [AIMA](https://hellyeahai.com/aima) in the Hellyeah app. It researches the business, plans the campaign, generates creatives, and launches after approval.

Both run on one system for campaigns, creatives, billing, and analytics.

## Do I need a coding agent to use Hellyeah? [#do-i-need-a-coding-agent-to-use-hellyeah]

Only for the developer path. The CLI is built for agents first, while [AIMA](https://hellyeahai.com/aima) runs campaign work in the Hellyeah app.

## Which ad platforms are supported? [#which-ad-platforms-are-supported]

**Today:** Google Ads (search and Performance Max).

**Not yet:** Meta Ads, TikTok Ads, multi-channel attribution. These are on the roadmap, not in v1.

## Can I use my own Google Ads account? [#can-i-use-my-own-google-ads-account]

Not in v1. Hellyeah launches campaigns on a managed pool of accounts that we own. You don't need to set up Google Ads yourself; we handle the account provisioning. If you have specific account-portability needs, get in touch.

## How does billing work? [#how-does-billing-work]

Hellyeah uses a **prepaid wallet**. You top up via Stripe Checkout from the CLI (`hellyeah wallet topup --amount <usd>`). Submitting a campaign debits its budget before internal review, and refundable funds return automatically. There's no monthly subscription. You pay for ad spend plus a thin platform fee.

## What happens to unused budget when I cancel a campaign? [#what-happens-to-unused-budget-when-i-cancel-a-campaign]

If Google Ads setup has not happened, withdrawing the request immediately refunds the full debited budget. Once a platform campaign exists, unspent budget refunds after the 48-hour settlement window. Check `hellyeah billing refunds` for the status.

## Is X-Ray free? Is it separate? [#is-x-ray-free-is-it-separate]

[X-Ray](/tracking) is Hellyeah's headless analytics. It's included with every Hellyeah account, with no separate subscription. You can also use X-Ray standalone if you only want analytics without running ads.

## Can my coding agent move money without asking me? [#can-my-coding-agent-move-money-without-asking-me]

No. The CLI requires human approval for every money movement:

* **Wallet top-ups** open Stripe Checkout in your browser, where you confirm the amount.
* **Campaign launches** require `--yes` and prompt the agent to confirm with the human first.
* **Daily budget caps** stay put. The ad platform enforces them, and the agent can't raise them without asking you.

The agent surfaces what it's about to spend, and you say yes or no.

## What data does Hellyeah collect from my website? [#what-data-does-hellyeah-collect-from-my-website]

If you install [X-Ray](/tracking):

* Pageviews, click events, form submits, outbound links, web vitals (autocapture)
* Custom events you fire via `track()`
* User identifiers you pass via `identify()`: emails and phone numbers are SHA-256 hashed before storage, and raw PII is not stored.

If you use the CLI without X-Ray, Hellyeah doesn't see your site traffic. We see the business profile fields you provide and the campaign data you launch, nothing more.

## How do creatives stay on-brand? [#how-do-creatives-stay-on-brand]

Every creative locks to your **business profile**: name, website, industry, tone, value proposition, and any saved brand colors or logos. The agent can iterate on hooks and angles, but it can't generate creatives for a different brand. Update the profile (`hellyeah profile update`) and creatives shift with it. The lock is the safety rail.

## Can I cancel a campaign mid-flight? [#can-i-cancel-a-campaign-mid-flight]

Yes. Run `hellyeah campaign cancel <id> --yes` from the CLI, or cancel it in the Hellyeah app. Before Google Ads setup, withdrawal refunds the full budget immediately. After setup, cancellation stops further spend and returns the unspent amount after settlement; existing impressions and clicks are billed normally.

## Why is the CLI "agent-first"? [#why-is-the-cli-agent-first]

Because coding agents do most of the work. The CLI returns JSON by default when piped, ships structured errors with `next` commands the agent can run to recover, and skips interactive prompts in the hot path. Humans get TTY-friendly output when they run the CLI directly. Both share the same commands. See [Concepts](/cli/concepts).

## Do you support self-hosting? [#do-you-support-self-hosting]

No. Hellyeah is a hosted product. The CLI and SDKs are open to install; campaign launch, creative generation, wallet, and X-Ray analytics run on Hellyeah.

## Where do I report a bug or request a feature? [#where-do-i-report-a-bug-or-request-a-feature]

Run `hellyeah feedback "your message"` from the CLI. When a coding agent crashes, pipe a structured payload into `hellyeah feedback` (see [Command reference → Feedback](/cli/reference#feedback)).

## How do I contact a human? [#how-do-i-contact-a-human]

If you're stuck, the fastest path is `hellyeah feedback "<your question>" --kind suggestion`. We read every feedback note. For partnership or press inquiries, reach out via the contact link on hellyeahai.com.


---

# Hellyeah Docs (/)



Welcome to the Hellyeah docs.

Pick a path:

* [Get Started](/intro): what Hellyeah is, plus the agent and manual paths
* [CLI](/cli): the `hellyeah` command and agent skills
* [Tracking](/tracking): the X-Ray SDK for pageviews, events, and conversions
* [AIMA](https://hellyeahai.com/aima): one agent that plans campaigns and launches them after approval
* [Billing & Safety](/billing-safety): wallets, approvals, refunds, and privacy


---

# Spend Approvals (/billing-safety/approvals)



Agents can prepare work. Humans approve money movement.

## Top-ups [#top-ups]

Wallet top-ups always go through Stripe Checkout in your browser. The agent cannot enter card details or charge a saved card on its own.

## Campaign launches [#campaign-launches]

The CLI launch command requires explicit approval:

```bash
hellyeah campaign launch ... --yes
```

Coding agents should show the plan, budget, and expected launch details before running the approved command.

## Budget approval [#budget-approval]

AIMA waits for approval of the pre-launch campaign budget. It cannot change a live campaign. CLI budget or spend changes remain separate human-approved actions.

## What agents can do [#what-agents-can-do]

* Research the business
* Draft a profile
* Generate creatives
* Create campaign plans
* Report performance

## What agents cannot do on their own [#what-agents-cannot-do-on-their-own]

* Add wallet funds
* Launch a paid campaign
* Raise spend limits
* Change brand profile locks


---

# Cancellations and Refunds (/billing-safety/cancellations-refunds)



Campaigns can be paused, resumed, or canceled from the CLI.

## Pause [#pause]

```bash
hellyeah campaign pause <campaign-id>
```

Pausing stops active delivery without closing the campaign.

## Resume [#resume]

```bash
hellyeah campaign resume <campaign-id>
```

Resuming restarts delivery using the existing campaign settings.

## Cancel [#cancel]

```bash
hellyeah campaign cancel <campaign-id> --yes
```

Withdrawing a request before Google Ads setup refunds its full debited budget immediately. Cancelling a platform-backed campaign stops further delivery and schedules its unspent budget to return after settlement.

## Refund timing [#refund-timing]

Pre-platform requests have no ad-platform spend to reconcile, so their full refund is immediate. Platform-backed campaigns wait for final spend to settle; this protects against delayed click and impression charges.

Check refund status with:

```bash
hellyeah billing refunds
```


---

# Data and Privacy (/billing-safety/data-privacy)



Hellyeah collects the data needed to run campaigns, report performance, and improve conversion tracking.

## Business profile [#business-profile]

The business profile includes fields such as business name, website URL, industry, audience, tone, value proposition, and campaign goal. Creatives lock to this profile.

## Campaign data [#campaign-data]

Hellyeah stores campaign configuration, budget reservations, creative snapshots, launch status, and performance metrics.

## X-Ray events [#x-ray-events]

If you install X-Ray, Hellyeah collects pageviews, autocaptured events, custom events, conversions, attribution fields, and session metadata.

## Known users [#known-users]

When you call `identify()`, email and phone values are normalized and hashed before storage. Raw contact details are not stored.

## Without X-Ray [#without-x-ray]

If you use the CLI without installing X-Ray, Hellyeah does not receive your website traffic. Campaign reporting is limited to ad-platform metrics.


---

# Billing & Safety (/billing-safety)



Hellyeah is built so agents can do the work without moving money or changing business-critical settings on their own.

## The model [#the-model]

* **Prepaid wallet.** Campaigns spend from a wallet you fund.
* **Human approval.** Top-ups and launches require explicit confirmation.
* **Funded requests.** Campaign submissions debit budget before internal review; approval never charges twice.
* **Refunds.** Pre-platform withdrawals refund in full immediately. Platform-backed campaigns return unspent budget after settlement.
* **Profile lock.** Creatives generate from the confirmed business profile.

## Read next [#read-next]

* [Wallets and top-ups](/billing-safety/wallets)
* [Spend approvals](/billing-safety/approvals)
* [Cancellations and refunds](/billing-safety/cancellations-refunds)
* [Data and privacy](/billing-safety/data-privacy)


---

# Wallets and Top-Ups (/billing-safety/wallets)



Hellyeah uses a prepaid wallet.

## Check balance [#check-balance]

```bash
hellyeah wallet balance
```

## Add funds [#add-funds]

```bash
hellyeah wallet topup --amount 200
```

The command opens Stripe Checkout in your browser for the amount you pass (USD). You enter payment details in Stripe and confirm the charge.

## Campaign funding [#campaign-funding]

When you submit a campaign launch, Hellyeah debits the campaign budget before the request enters internal review. Approval does not debit the wallet a second time. If the request is rejected or withdrawn before Google Ads setup, the full amount returns immediately.

## Platform fee [#platform-fee]

Campaign spend and platform fees come from the wallet. Reports show campaign spend separately from available wallet balance.


---

# Concepts (/cli/concepts)



Four ideas explain how the Hellyeah CLI works and why it's shaped this way.

## Agent-first [#agent-first]

The CLI is built for agents first, usable by humans. Every design decision optimizes for machine consumption.

JSON output by default when piped. Structured error envelopes with `next` commands so the agent can self-correct. No interactive prompts in the hot path, with explicit flags everywhere for scripted use.

Humans get the same commands with TTY-friendly output: tables, spinners on stderr, one-line confirmations. Both audiences hit the same surface. The agent is the primary user, and humans get a clean fallback on the same commands.

## Vibe vs Workflow [#vibe-vs-workflow]

The CLI supports two interaction modes. Both use the same command surface. The difference is how the agent sequences calls and how often it checks in with the human.

**Vibe Mode.*&#x2A; One prompt, one plan, one launch. The user says &#x2A;"run ads for my landing page"* and the agent takes it from there: researches the business, generates creatives, drafts a campaign, presents a polished plan. The human touches two things: top up the wallet and approve the launch. Everything in between is autonomous.

**Workflow Mode.** Linear and stage-gated, with confirmation between steps:

1. Confirm brand: business details the agent extracted
2. Confirm creatives: generated or uploaded assets
3. Confirm draft: budget, audience, copy, schedule
4. Launch

Each stage persists intermediate state, so you can pause and resume across sessions. Use this when you want to stay in the loop or when the flow is long-running.

Modes are a caller convention, not a CLI flag. The same commands work for both.

## Money safety [#money-safety]

Wallet top-up is the human's job. The CLI opens Stripe Checkout in your browser, where only you can enter card details and confirm the amount. The agent never moves money on its own.

Every campaign submission debits its full budget from the wallet. The launch command requires `--yes` to authorize that debit. A rejected or withdrawn request that has not reached Google Ads receives an immediate full refund. Once platform delivery can have occurred, cancellation refunds only unspent cents after the settlement window.

Amounts travel as integer cents on the wire and convert to USD at the CLI boundary. No float math, no rounding bugs. If you see a number on the wire, it's cents.

## Campaign launches [#campaign-launches]

The launch command funds and submits a campaign for internal review. The API snapshots the selected creatives and debits the budget immediately. Approval later assigns the ad account, creates the Google Ads campaign with the selected audience and locations, and wires conversion signals from X-Ray when tracking is configured.

Google Ads is the launch platform today. Meta, TikTok, and other channels are not part of v1.

## Profile-locked creatives [#profile-locked-creatives]

Creatives lock to your business profile. Business context, audience defaults, tone, and any saved brand colors or logos all resolve server-side from the profile you've already saved. The CLI surface has no flag to override them.

The agent can iterate angles (hook, tone, novelty), narrow the audience for a specific push, or steer toward a campaign theme. It cannot inject brand colors, logos, business descriptions, or platform dimensions. Everything that defines "this is *our* ad" is locked.

That's why the profile gate is a hard prerequisite: with no profile, there's nothing to anchor a creative to, and generation is refused.

Text creatives are live. Image generation can be queued by the CLI where enabled for your account; video is not part of v1.


---

# Connect Your Coding Agent (/cli/connect-agent)



The CLI gives your agent commands. The skill teaches it when to run them, how to chain them, and where to pause for human approval.

## Install the skill [#install-the-skill]

```bash
hellyeah skills add hellyeah --global --yes
```

This installs the Hellyeah skill into your local agent skill directory.

Target a specific agent when you want to be explicit:

```bash
hellyeah skills add hellyeah --global --agent claude-code
hellyeah skills add hellyeah --global --agent cursor
```

## What the skill teaches [#what-the-skill-teaches]

* Research the website before drafting a business profile
* Generate creatives from the confirmed profile
* Create or link an X-Ray tracker before launch when conversion tracking matters
* Ask before wallet top-ups and campaign launches
* Use structured CLI output to recover from validation errors

## Try it [#try-it]

After installing the skill, ask your coding agent:

> launch ads for my landing page

For a step-by-step walkthrough, continue to [Launch your first ad](/cli/launch-ads).

<Callout title="Prompt for your agent" type="info">
  If your agent hasn't picked up the skill yet, paste this instead. It forces a load of the Hellyeah skill before doing anything:

  ```text
  Use the Hellyeah skill to launch ads for my landing page.

  Constraints:
  - Read my website first and propose a business profile. Wait for me to approve it before saving.
  - Generate creatives only after the profile is saved.
  - Pause for explicit approval before `hellyeah wallet topup` and before `hellyeah campaign launch`.
  - If any command fails validation, show me the structured error and propose a fix. Do not retry blindly.
  ```
</Callout>


---

# Hellyeah CLI (/cli)



The `hellyeah` CLI gives your coding agent one command surface for the things it can't do on its own: signing in, funding a wallet, generating creatives, launching Google Ads, and provisioning analytics trackers.

Install the skill once and Claude Code, Cursor, Codex, Replit Agent, Windsurf, or v0 can drive the workflow end to end. Conversion data lives in [Tracking](/tracking).

## What you get [#what-you-get]

* **One kit.** Install once, then bare `hellyeah` covers ads, wallets, creatives, and tracker provisioning under one command.
* **One safety model.** Money moves only after explicit approval. Wallet top-ups and campaign launches always pause for a human "yes". The agent never moves dollars on its own.
* **Structured output.** Every command returns a JSON envelope when piped, with `next` actions an agent can use to recover from errors.

## What the CLI can do [#what-the-cli-can-do]

* Research and save a business profile from your website
* Generate brand-locked ad copy and creative assets
* Launch Google Ads campaigns with approved budgets and targeting
* Pause, resume, cancel, and report on campaigns
* Provision an X-Ray tracker for conversion analytics (the SDK lives in [Tracking](/tracking))

## Next [#next]

* [Install](/cli/install): set up the CLI and connect your coding agent
* [Connect your coding agent](/cli/connect-agent): install the Hellyeah skill
* [Launch your first ad](/cli/launch-ads): end-to-end walkthrough
* [Tracking](/tracking): wire up the X-Ray analytics SDK
* [Troubleshooting](/cli/troubleshooting): common fixes


---

# Install (/cli/install)



Install once. Then ask your agent to launch ads.

## 1. Install the CLI [#1-install-the-cli]

Pick your platform or package manager. The **native installer** (curl / PowerShell) is recommended: it downloads the matching native binary, verifies its checksum, and puts `hellyeah` on your PATH with no Node required. npm and npx are alternatives for environments already standardized on Node.

<Tabs items="[&#x22;curl&#x22;, &#x22;Windows&#x22;, &#x22;npm&#x22;, &#x22;npx&#x22;]">
  <Tab value="curl">
    **Recommended** · macOS & Linux · no Node required.

    ```bash
    curl -fsSL https://hellyeah.sh/install.sh | sh -s -- --agents -y
    ```

    Installs Hellyeah and the agent skills.
  </Tab>

  <Tab value="Windows">
    **Recommended** · PowerShell · no Node required.

    ```powershell
    powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://hellyeah.sh/install.ps1 | iex"
    ```

    Installs to `%LOCALAPPDATA%\Programs\Hellyeah\bin\hellyeah.exe` and updates your user PATH.

    Prefer to review the script before running it? Download, inspect, then run:

    ```powershell
    irm https://hellyeah.sh/install.ps1 -OutFile install.ps1
    notepad .\install.ps1
    powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
    ```
  </Tab>

  <Tab value="npm">
    Alternative · requires Node · installs the `hellyeah` wrapper globally onto your PATH.

    ```bash
    npm i -g hellyeah@latest
    ```
  </Tab>

  <Tab value="npx">
    Alternative · requires Node · resolves the latest version, then runs the bundled installer.

    ```bash
    npx hellyeah@latest install
    ```
  </Tab>
</Tabs>

### Custom install location [#custom-install-location]

The native installer writes to a default prefix. Point it somewhere writable when you need to:

```bash
curl -fsSL https://hellyeah.sh/install.sh | HELLYEAH_INSTALL_DIR="$HOME/.local" sh -s -- --agents -y
```

That writes the Unix binary to `$HOME/.local/bin/hellyeah`. On Windows:

```powershell
$env:HELLYEAH_INSTALL_DIR="$HOME\Programs\Hellyeah"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://hellyeah.sh/install.ps1 | iex"
```

### Verify [#verify]

```bash
hellyeah --help
```

If the installer printed an `export` line because it could not update your PATH automatically, run it now. For example:

```bash
export PATH="$HOME/.hellyeah/bin:$PATH"
```

Otherwise reload your shell with `exec $SHELL` (or open a new terminal; on Windows, always open a new terminal). The exact directory to add is the one printed during step 1.

Update later with:

```bash
hellyeah update
```

Standalone installs re-run the verified installer into the same directory, so this also repairs a stale binary in place. On Windows, the replacement is scheduled after the current `hellyeah.exe` process exits.

## 2. Log in [#2-log-in]

```bash
hellyeah auth login
```

This opens your browser to the Hellyeah sign-in page. After you authenticate, the CLI stores credentials under `~/.config/hellyeah/` and refreshes them as needed. First-time login auto-creates a Hellyeah account.

Verify:

```bash
hellyeah auth whoami
```

## 3. Connect your agent [#3-connect-your-agent]

The curl install command already installs the skills. If you used Windows, npm, npx, or skipped `--agents`, run:

```bash
hellyeah skills add hellyeah --global --yes
```

Target a specific agent with `--agent`:

```bash
hellyeah skills add hellyeah --global --agent claude-code
hellyeah skills add hellyeah --global --agent cursor
```

## Done [#done]

Your coding agent now knows how to use the CLI. Ask it:

> "launch ads for my landing page"

and it takes over: researches your business, generates creatives, drafts a campaign, asks you to confirm funding and launch. Walk through it end to end in [Launch your first ad](/cli/launch-ads).

<Callout title="Prompt for your agent" type="info">
  Paste this into Claude Code, Cursor, or any agent that runs shell commands to bootstrap a fresh machine:

  ```text
  Install the Hellyeah CLI on this machine.

  1. Install Hellyeah for this OS: on macOS/Linux run `curl -fsSL https://hellyeah.sh/install.sh | sh -s -- --agents -y`; on Windows run `powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://hellyeah.sh/install.ps1 | iex"` and then `hellyeah skills add hellyeah --global --yes`. Confirm `hellyeah --help` works afterwards. If the binary isn't found, tell me which directory to add to PATH.
  2. Run `hellyeah auth login` and wait for the browser flow to finish, then verify with `hellyeah auth whoami`.
  3. Make sure the Hellyeah skill is installed so you (the agent) know how to drive the CLI.
  4. Print a one-line confirmation with my account email and the installed CLI version.

  Do not launch any campaigns yet.
  ```
</Callout>

## Environment & config [#environment--config]

Most users won't need this section. Use it only when Hellyeah support asks you to inspect or override the CLI connection settings.

**Resolution order** (first match wins per field):

1. Environment variables: `HELLYEAH_API_URL`, `HELLYEAH_AUTH_PUBLISHABLE_KEY`, `HELLYEAH_AUTH_CLIENT_ID`
2. Config file: `~/.config/hellyeah/config.json`
3. Production defaults baked into the release binary

**Config file example** (`~/.config/hellyeah/config.json`):

```json
{
  "apiUrl": "https://api.hellyeahai.com",
  "authPublishableKey": "pk_...",
  "authClientId": "cli_..."
}
```

**Inspect resolved config:**

```bash
hellyeah config status
```

Prints the resolved API URL, auth settings, config file path, and credential state as JSON.


---

# Launch your first ad (/cli/launch-ads)



Five steps from zero to a live Google Ads campaign. In practice your coding agent runs all of this for you. What follows is what it does, command by command, and where it pauses for your approval.

## 1. Set your profile [#1-set-your-profile]

The profile is your business identity. Every creative anchors to it.

```bash
hellyeah profile update \
  --business-name "Acme" \
  --website-url "https://acme.com" \
  --industry "e-commerce" \
  --description "Acme sells premium widgets to small businesses" \
  --target-audience "Small business owners in the US" \
  --tone "professional, approachable" \
  --value-proposition "High-quality widgets at wholesale prices" \
  --main-goal "Drive online sales" \
  --brand-colors '["#ff4d2e","#111827"]'
```

Check completeness:

```bash
hellyeah profile get
```

All eight text fields are required before you can launch. Brand colors and logos are optional for current creative generation; include them when available and omit them when they are not. Platform-specific launch flows can still require additional assets. The agent usually researches your website to fill these in, then asks you to approve the draft.

## 2. Fund your wallet [#2-fund-your-wallet]

Hellyeah is prepaid. Every submitted launch debits its budget from the wallet.

```bash
hellyeah wallet topup --amount 70
```

This opens Stripe Checkout in your browser for the amount you passed. **You** approve the charge and enter card details. The CLI polls until the payment is confirmed.

Verify:

```bash
hellyeah wallet balance
```

This is the first of two moments where money moves and the human is in the loop.

## 3. Generate creatives [#3-generate-creatives]

```bash
# Ad copy (synchronous, returns variants in one round trip)
hellyeah creative generate text --hook curiosity_gap --tone playful

# Image (asynchronous, returns a jobId to poll)
hellyeah creative generate image --hook before_after --reference mercury --size all
```

`--size all` generates the full display kit (landscape + square) in one call. Both commands lock to your profile, so saved brand colors, logos, and business context come from the saved profile and cannot be overridden via flags. Brand colors and logos are optional for current creative generation; generation still works when they are not set. Launch integrations can still enforce platform-specific asset requirements.

Poll image jobs with:

```bash
hellyeah creative status --job-id <jobId> --watch
```

## 4. Launch the campaign [#4-launch-the-campaign]

```bash
hellyeah campaign launch \
  --name "Q2 Launch" \
  --text-id <text-job-id> \
  --image-id <landscape-job-id> \
  --image-id <square-job-id> \
  --budget 500 \
  --budget-type total \
  --end-date "2026-08-31T00:00:00Z" \
  --keyword "premium widgets" \
  --location "United States" \
  --yes
```

CLI launch uses a lifetime total budget, and `--end-date` is always required so the API has a delivery window for pacing. `--budget-type` is optional; if you include it, the only accepted value is `total`. Dates accept either `YYYY-MM-DD` or a full ISO 8601 timestamp with `Z`.

`--yes` is mandatory. The agent will ask you to confirm before money moves. When you submit, Hellyeah debits the full campaign budget and places the funded request in internal review.

Submission is durable and idempotent: the API snapshots your creatives, records the wallet transaction, completes the debit, and then returns a campaign id in `pending_internal_review`. It does not assign an ad account or create anything in Google Ads until the request is approved.

The CLI safely retries one dropped response with the same launch key. If it still cannot tell whether submission completed, follow the returned retry command: it includes `--idempotency-key` so a new CLI process resumes the same campaign and debit. Omit that flag when you intentionally want a separate campaign.

Google Ads is the supported launch platform today. The campaign uses your approved plan: budget, audience, locations, selected creatives, and any X-Ray conversion signals you've connected through [Tracking](/tracking).

## 5. Watch it run [#5-watch-it-run]

```bash
# Status + cached performance metrics (spend, clicks, conversions)
hellyeah campaign status <campaign-id>

# After approval, pause or resume delivery; cancel at any stage
hellyeah campaign pause <campaign-id>
hellyeah campaign resume <campaign-id>
hellyeah campaign cancel <campaign-id> --yes
```

Withdrawing a request before a Google Ads campaign exists refunds the full debited budget immediately. After a campaign reaches Google Ads, cancellation waits through the 48-hour platform settlement window and then refunds the unspent amount automatically.

***

**Vibe mode vs Workflow mode.** In vibe mode the agent runs through all five steps autonomously, pausing only at funding and launch approval. In workflow mode it stops between each step for your confirmation.

<Callout title="Prompt for your agent" type="info">
  Drop this into your agent to drive the full five-step flow end-to-end:

  ```text
  Launch a Google Ads campaign for the business at <YOUR_URL>.

  Budget: $<AMOUNT> total. Audience: <ONE_LINE>. Primary goal: <SIGNUPS | PURCHASES | LEADS>.

  Steps:
  1. Research the site and propose a profile via `hellyeah profile update`. Show me the draft and wait for approval.
  2. Run `hellyeah profile get` and confirm all eight fields are populated.
  3. Generate ad copy (`hellyeah creative generate text`) and a reference-led full display kit (`hellyeah creative generate image --reference <id> --size all`). Poll image jobs with `hellyeah creative status --watch`.
  4. Show me the wallet balance. If insufficient, pause and ask before running `hellyeah wallet topup --amount <usd>`.
  5. Draft the final `hellyeah campaign launch` command with `--yes` omitted. Show it to me. Only run it after I reply "go".

  Use `hellyeah campaign status <id>` after launch to track spend and performance.
  ```
</Callout>


---

# Command reference (/cli/reference)



Every Hellyeah CLI command, grouped by surface. One line per command. For deep dives, see [Concepts](/cli/concepts) and [Launch your first ad](/cli/launch-ads).

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](#output-contract).

## Auth [#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`

```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 [#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`

```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 [#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`

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

## Billing [#billing]

Refund status for canceled or failed campaign reservations.

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

**Example:** `hellyeah billing refunds --json`

```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 [#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`

```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 [#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`

```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 [#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`

```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 [#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`

```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 [#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`

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

***

## Output contract [#output-contract]

The wire-level agreement every command obeys.

**JSON envelope (success):**

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

**JSON envelope (error):**

```json
{
  "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:**

| Exit  | Meaning                                                             |
| ----- | ------------------------------------------------------------------- |
| `0`   | Success                                                             |
| `1`   | Generic error: inspect `error.code` on stdout                       |
| `2`   | Usage error: bad flag or missing argument (`validation_error`)      |
| `3`   | Authentication error (`unauthenticated`, `unauthorized`)            |
| `4`   | Payment / wallet error (`insufficient_balance`, `payment_timeout`)  |
| `5`   | Rate limit exceeded (`rate_limited`: wait for `retryAt` then retry) |
| `130` | Cancelled by `Ctrl+C` during a polling command                      |

**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.


---

# Troubleshooting (/cli/troubleshooting)



## `hellyeah: command not found` [#hellyeah-command-not-found]

You haven't run the install bootstrap yet, or the install directory isn't on your shell's PATH. Run:

```bash
curl -fsSL https://hellyeah.sh | sh
```

The output tells you which directory contains the installed binary (by default `~/.hellyeah/bin`). If the installer printed an `export` line because it could not update your PATH automatically, run it:

```bash
export PATH="$HOME/.hellyeah/bin:$PATH"
```

Otherwise reload your shell:

```bash
exec $SHELL
hellyeah --help
```

On Windows, use a new terminal after installing:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://hellyeah.sh/install.ps1 | iex"
hellyeah --help
```

If another binary is shadowing the installed one:

```powershell
where.exe hellyeah
```

The Hellyeah install path should appear before any older `hellyeah.exe`.

## Install fails or fetch is slow [#install-fails-or-fetch-is-slow]

The installer downloads a native binary from `https://releases.hellyeahai.com/cli` and verifies it against `checksums.txt`. If the network drops, retry:

```bash
curl -fsSL https://hellyeah.sh | sh
```

If you already have Node/npm and need the npm fallback:

```bash
npm exec --yes --package hellyeah@latest -- hellyeah install
```

If the installer cannot write to its target directory, choose a writable prefix:

```bash
curl -fsSL https://hellyeah.sh | HELLYEAH_INSTALL_DIR="$HOME/.local" sh
```

On Windows:

```powershell
$env:HELLYEAH_INSTALL_DIR="$HOME\Programs\Hellyeah"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://hellyeah.sh/install.ps1 | iex"
```

Windows binaries are initially unsigned. SmartScreen or Defender may warn on first run; inspect `https://hellyeah.sh/install.ps1` and the release `checksums.txt` if your environment requires an audit trail.

To uninstall a Windows standalone install:

```powershell
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Programs\Hellyeah"
```

Then remove `%LOCALAPPDATA%\Programs\Hellyeah\bin` from your user PATH.

On Alpine or another minimal musl system, install the C++ runtime first if the installer says the downloaded binary cannot start:

```bash
apk add libstdc++ libgcc
```

## Auth looks stale [#auth-looks-stale]

Check the current account:

```bash
hellyeah auth whoami
```

If it is wrong, sign out and sign in again:

```bash
hellyeah auth logout
hellyeah auth login
```

## The agent does not know Hellyeah commands [#the-agent-does-not-know-hellyeah-commands]

Install or reinstall the skill:

```bash
hellyeah skills add hellyeah --global --yes
```

Then restart the agent session so it reloads local skills.

## Launch fails because the wallet is low [#launch-fails-because-the-wallet-is-low]

Top up the prepaid wallet, then rerun the launch:

```bash
hellyeah wallet topup --amount 50
hellyeah wallet balance
```

Wallet top-ups open Stripe Checkout in your browser. Your agent cannot enter card details or add funds on its own.

## Tracking is not linked [#tracking-is-not-linked]

Create or inspect the org tracker:

```bash
hellyeah tracker state --json
hellyeah tracker create --domain <host> --json
```

If you do not have a production domain yet, use `hellyeah tracker create --pre-launch --json`, then update the same tracker with `hellyeah tracker update --domain <host>` when you launch.

Install the SDK with [Tracking](/tracking) or the [Install the SDK guide](/tracking/install-sdk).

## Report a bug [#report-a-bug]

Send feedback from the CLI:

```bash
hellyeah feedback "what happened"
```

The positional message is filed as `kind: "note"`. For structured agent reports (crashes, suggestions), pipe JSON to `hellyeah feedback` — see the [reference](/cli/reference#feedback).


---

# What is Hellyeah (/intro)



## The problem [#the-problem]

A coding agent can stand up a landing page in an afternoon. Getting that page in front of customers still takes weeks, because it means a separate stack: ad accounts, billing, creatives, tracking pixels, analytics. None of that lives in your editor, so it usually doesn't get done.

## The solution [#the-solution]

Hellyeah gives your coding agent the cloud-side tools it doesn't have on its own: moving money, calling Google Ads, writing creatives, and provisioning X-Ray trackers. Install the CLI and your agent has one command surface for all of it. Add the X-Ray SDK to your app when you want pageviews, events, and conversions flowing back into campaign reports. You stay in your editor. The installed Hellyeah skill tells your agent how to sequence the commands and when to ask you for approval.

## Two paths [#two-paths]

**Developers** drive the system from a terminal. Install the [CLI](/cli), point your coding agent at the skill, and say "launch ads for my landing page." The agent handles research, creatives, budget, and launch.

**Business owners** use [AIMA](https://hellyeahai.com/aima). It learns the business, plans the campaign, writes the ads, and launches after approval.

## Next steps [#next-steps]

* [Quickstart](/intro/quickstart): five commands and your agent is launching ads
* [Products](/intro/products): the CLI, AIMA, and X-Ray at a glance


---

# Products (/intro/products)



Hellyeah ships three top-level sections on the same campaign, creative, billing, and analytics system. Pick the surface that matches how you work.

| Section                                 | What it is                                                                                                                    | How you access it                                                                      |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [**CLI**](/cli)                         | The `hellyeah` command and agent skill. Your coding agent uses it to launch and manage Google Ads.                            | [Install the CLI](/cli/install), then [connect your coding agent](/cli/connect-agent). |
| [**Tracking**](/tracking)               | The `@hellyeah/x-ray` SDK. Captures pageviews, custom events, and conversions and sends them back into your campaign reports. | [Install the SDK](/tracking/install-sdk) in your app.                                  |
| [**AIMA**](https://hellyeahai.com/aima) | One agent that researches your business, plans campaigns, generates creatives, and launches ads after approval.               | Open AIMA in the [Hellyeah app](https://app.hellyeahai.com).                           |

## CLI [#cli]

The `hellyeah` CLI is built for agents first. Your coding agent calls it to fund a wallet, research a brand, generate creatives, launch a campaign, and provision tracking, all from your editor. Humans get the same commands with TTY-friendly output.

Start with the [Quickstart](/intro/quickstart) or jump into the [CLI](/cli).

## Tracking [#tracking]

`@hellyeah/x-ray` is headless analytics: pageviews, custom events, conversions, attribution, and `identify()`. Conversion signals feed back into Google Ads, so it optimizes against real conversions instead of guesses. Conversion data also closes the loop in your campaign reports.

See [Tracking](/tracking) for the full setup.

## AIMA [#aima]

AIMA handles campaign work in one place. Give it your domain, then approve the business profile, campaign plan, creative, and budget before launch.

See [AIMA](https://hellyeahai.com/aima) for the current product overview.

## Shared capabilities [#shared-capabilities]

All three surfaces share the same core capabilities:

* **Campaign launches** turn an approved plan into a live Google Ads campaign with budget, targeting, creatives, and conversion wiring.
* **Brand-locked creatives** generate copy and assets from your confirmed business profile so ads stay on-brand.
* **Wallet safety** debits campaign funding from a prepaid balance only after explicit approval.
* **Conversion tracking** connects X-Ray events back into reports so you can see what happens after the click.

## Billing & Safety [#billing--safety]

Billing and safety rules are shared everywhere: a prepaid wallet, explicit approval before top-ups and campaign debits, immediate full refunds before platform setup, and delayed unspent refunds when ad-platform settlement is required.

See [Billing & Safety](/billing-safety) for the full model.


---

# Quickstart (/intro/quickstart)



Both tabs end at the same place: a live Google Ads campaign. The difference is how much you do by hand. Pick the one that fits.

<Tabs items="[&#x22;Agent&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Agent">
    ## 🤖 Agent path [#-agent-path]

    Give your coding agent one prompt. It runs the install, signs in, drafts the brand profile, generates creatives, and asks you to approve funding and launch. Works with Claude Code, Cursor, Codex, Replit Agent, Windsurf, or v0.

    ### Copy this prompt [#copy-this-prompt]

    Paste the block below into your coding agent. It bootstraps the CLI, installs the Hellyeah skill, and hands the rest of the work to the skill, which signs you in and takes it from there. No custom instructions needed.

    ```text
    Set up Hellyeah and use it to launch a Google Ads campaign for the site I'm currently working on:

    1. Install the CLI and skills: on macOS/Linux run `curl -fsSL https://hellyeah.sh/install.sh | sh -s -- --agents -y`; on Windows run `powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://hellyeah.sh/install.ps1 | iex"` and then `hellyeah skills add hellyeah --global --yes`.
    2. Confirm `hellyeah --help` works.
    3. Load the skill and follow its instructions to launch ads. It signs me in first (a browser opens for me to register or log in), then walks through the rest.
    ```

    That's the whole prompt. The skill carries the workflow: sign-in, research, creatives, plan, launch, and the two human approvals at funding and launch time. You don't need to spell any of it out.

    ### What to expect [#what-to-expect]

    * **One install.** The installer runs once. Everything after is bare `hellyeah <cmd>`.
    * **You register and log in.** The skill opens your browser to sign in before it does anything that needs your account. That's where you sign up or sign in.
    * **Two approvals later.** The skill pauses for your "yes" before money moves: once at wallet top-up, once at campaign launch.
  </Tab>

  <Tab value="Manual">
    ## 🛠 Manual path [#-manual-path]

    Run every command yourself. The CLI walks you through profile, wallet, creative, and launch, with no agent in the middle.

    ### 1. Install the CLI [#1-install-the-cli]

    Install once. After this, every command is bare `hellyeah <cmd>`.

    ```bash
    curl -fsSL https://hellyeah.sh | sh
    ```

    Windows:

    ```powershell
    powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://hellyeah.sh/install.ps1 | iex"
    ```

    The native installer is recommended. If you'd rather install through Node, `npm i -g hellyeah@latest` and `npx hellyeah@latest install` both work. See [all install options](/cli/install#1-install-the-cli).

    Verify:

    ```bash
    hellyeah --help
    ```

    If the installer printed an `export PATH=...` line because it couldn't update your PATH, run it (or open a new terminal) before verifying.

    ### 2. Sign up and log in [#2-sign-up-and-log-in]

    First check whether you are already signed in:

    ```bash
    hellyeah auth whoami
    ```

    If that prints your account, you are set. Skip to step 3. Only if it reports you are not signed in, run:

    ```bash
    hellyeah auth login
    ```

    This opens your browser. Authenticate with Google or email. First-time login auto-creates a Hellyeah account.

    ### 3. Set your business profile [#3-set-your-business-profile]

    The profile is the brand identity every creative anchors to. All eight text fields are required before launch. Brand colors and logos are optional for current creative generation, but you can include them to improve creative quality. Some future campaign types may require additional assets before launch.

    ```bash
    hellyeah profile update \
      --business-name "Acme" \
      --website-url "https://acme.com" \
      --industry "e-commerce" \
      --description "Acme sells premium widgets to small businesses" \
      --target-audience "Small business owners in the US" \
      --tone "professional, approachable" \
      --value-proposition "High-quality widgets at wholesale prices" \
      --main-goal "Drive online sales"
    ```

    Check completeness:

    ```bash
    hellyeah profile get
    ```

    ### 4. Fund your wallet [#4-fund-your-wallet]

    Hellyeah is prepaid, so campaign submissions debit your wallet.

    ```bash
    hellyeah wallet topup --amount 50
    ```

    This opens Stripe Checkout in your browser to charge the amount you passed. `--amount` is required.

    ```bash
    hellyeah wallet balance
    ```

    ### 5. (Optional) Set up tracking [#5-optional-set-up-tracking]

    For conversions in your campaign reports, provision a tracker and install the SDK now. You can skip this and add tracking later.

    ```bash
    hellyeah tracker create --domain acme.com --yes
    ```

    Use `hellyeah tracker create --pre-launch --yes` instead if you do not have a production domain yet.

    Then install the SDK. See [Install the SDK](/tracking/install-sdk) for framework snippets.

    ### 6. Generate creatives [#6-generate-creatives]

    Both commands lock to your profile. Saved brand colors, logos, and business context come from the saved profile; generation still works if colors or logos are not set.

    ```bash
    hellyeah creative generate text --hook curiosity_gap --tone playful
    hellyeah creative generate image --hook before_after --reference mercury --size all
    ```

    Poll image jobs:

    ```bash
    hellyeah creative status --job-id <jobId> --watch
    ```

    ### 7. Launch the campaign [#7-launch-the-campaign]

    ```bash
    hellyeah campaign launch \
      --name "Q2 Launch" \
      --text-id <text-job-id> \
      --image-id <landscape-job-id> \
      --image-id <square-job-id> \
      --budget 500 \
      --budget-type total \
      --end-date "2026-08-31T00:00:00Z" \
      --keyword "premium widgets" \
      --location "United States" \
      --yes
    ```

    CLI launch always uses a lifetime total budget, so `--end-date` is required. `--budget-type` is optional; if provided, its only accepted value is `total`.

    `--yes` is the explicit human approval for money to move. Submission snapshots the creatives, records and completes the wallet debit, and returns a funded campaign id in internal review. Ad-account assignment and Google Ads setup happen only after approval.

    ### 8. Watch performance [#8-watch-performance]

    ```bash
    hellyeah campaign status <campaign-id>
    hellyeah campaign pause <campaign-id>
    hellyeah campaign resume <campaign-id>
    hellyeah campaign cancel <campaign-id> --yes
    ```

    Withdrawing before Google Ads setup refunds the full budget immediately. After setup, cancellation stops further spend and refunds the unspent amount after the 48-hour settlement window.
  </Tab>
</Tabs>

## Next [#next]

* [CLI reference](/cli/reference): every command with example output
* [Tracking](/tracking): close the optimization loop with conversion data
* [Billing & Safety](/billing-safety): wallets, approvals, refunds, privacy


---

# API Reference (/tracking/api-reference)



Collection endpoints (`/api/send`, `/api/batch`) and `/api/config/:websiteId` are public so the tracker script and SDK can call them from end-user browsers. Protected X-Ray APIs are reserved for Hellyeah services and are not exposed to direct customer integrations.

## Collect [#collect]

Event ingestion. No auth required: the tracker script and client SDK call these directly from end-user browsers. Bot traffic is detected and dropped. Disabled trackers return `200` but discard the event.

* `POST /api/send`: Ingest a pageview, custom event, engagement update, or a single batch of events.
* `POST /api/batch`: Ingest a batch of events (tracker queue flush).
* `GET /api/config/:websiteId`: Tracker configuration for website initialization.

### Sample request [#sample-request]

```http
POST /api/send
Content-Type: application/json

{
  "type": "event",
  "payload": {
    "website": "your-website-id",
    "hostname": "acme.com",
    "url": "/pricing",
    "referrer": "https://google.com",
    "name": "signup_click",
    "data": { "plan": "pro" }
  }
}
```

### Sample response [#sample-response]

```json
{ "ok": true }
```


---

# Identify Users (/tracking/identify-users)



Use `identify()` when your app knows who the visitor is.

```ts
import { identify } from "@hellyeah/x-ray";

identify("user-123", {
  email: "user@example.com",
  phone: "+14155551234",
});
```

## What gets stored [#what-gets-stored]

Email and phone values are normalized and hashed before storage. Raw email addresses and phone numbers are not stored.

## When to call it [#when-to-call-it]

* After sign-up
* After login
* After checkout
* When a user submits a lead form

## Why it matters [#why-it-matters]

Identity improves reporting and conversion matching. It helps connect anonymous ad clicks to known outcomes while keeping raw contact details out of stored event data.


---

# Tracking (/tracking)



Tracking has two pieces:

* **`hellyeah tracker ...`** in the [CLI](/cli) provisions a tracker for your domain.
* **`@hellyeah/x-ray`** is the browser and server SDK you install in your app to collect pageviews, events, and conversions.

There is no separate X-Ray CLI or X-Ray account. X-Ray is the tracking layer inside Hellyeah: what the CLI provisions and what your app sends events to.

## Why tracking [#why-tracking]

Ad platforms optimize for the events you tell them are valuable. Without conversion data, Google Ads can only guess. Tracking closes the loop: it records pageviews, custom events, and conversion events from your site, then feeds those events back into Hellyeah so your campaign reports show what drove signups, purchases, or whatever else matters to your business.

## Create a tracker [#create-a-tracker]

A tracker represents one website. Its ID is the `websiteId` you pass to the SDK.

```bash
hellyeah tracker create --domain acme.com --yes
```

If you do not have a production domain yet, create a pre-launch tracker:

```bash
hellyeah tracker create --pre-launch --yes
```

Pre-launch trackers use an opaque `.invalid` placeholder and return
`domainPlaceholder: true`. When you launch, update the same tracker instead of
creating a new one:

```bash
hellyeah tracker update --domain acme.com --yes
```

Returns a `trackerId` (also valid as `websiteId`). If you already have one, inspect it:

```bash
hellyeah tracker state
```

## Install the SDK [#install-the-sdk]

The recommended way is to let your coding agent do it. Install the tracker skill once, and your agent detects the framework, provisions the tracker, installs `@hellyeah/x-ray`, and places the snippet in the right entry point:

```bash
hellyeah skills add tracker --global --yes
```

Then ask it to "add Hellyeah tracking to this project." It shows you the diff before writing and stops for your review. More on the agent flow lives on [Install the SDK](/tracking/install-sdk).

Prefer to wire it in by hand? Install the package and copy the snippet for your stack:

```bash
npm i @hellyeah/x-ray
```

See [Install the SDK](/tracking/install-sdk) for snippets for Next.js, Remix, Vue/Nuxt, Svelte, Astro, vanilla HTML, and Node/Bun servers.

## What tracking captures [#what-tracking-captures]

A short tour of what flows through tracking once it is live.

**Events.** Autocapture records pageviews, clicks, form submits, outbound link clicks, and web vitals out of the box. Use `track()` mainly for conversions and the few product events your team reports on.

**Conversions.** Import the `cv` constant from `@hellyeah/x-ray` on the client or `@hellyeah/x-ray/server` on the server, then call `track(cv.purchase, ...)` or `track(cv.leadSubmit, ...)`. The constants send `cv_*` event names without making you hardcode strings that can drift or break postbacks.

**Sessions.** Basic pageview and event tracking does not require a cookie banner because X-Ray can resolve visits without setting a personal-data cookie for the default flow.

**Attribution.** Click IDs (`gclid`, `fbclid`, `msclkid`, `ttclid`, `li_fat_id`, `twclid`, `gbraid`, `wbraid`) and `utm_*` fields are captured on first visit and retained for 90 days. Both first-touch and last-touch attribution models are available on reports.

**Identify.** Calling `identify()` connects an anonymous visitor to a known user. Email and phone are hashed before storage. Raw contact details are not stored.

## Privacy [#privacy]

X-Ray is designed to keep tracking data limited to attribution and reporting. Default tracking avoids raw contact details, hashes email and phone values passed through `identify()`, and stores click IDs and UTM parameters only so Hellyeah can connect campaign spend to outcomes.

For GDPR-sensitive sites, add tracking to your privacy notice, disclose the 90-day attribution retention window, and avoid sending personal data in custom event properties. If your consent policy requires analytics opt-in, mount the SDK only after the visitor has consented.

## Next [#next]

* [Install the SDK](/tracking/install-sdk): framework-specific snippets
* [Track events](/tracking/track-events): custom events and conversions
* [Identify users](/tracking/identify-users): known user identity, hashed PII
* [API reference](/tracking/api-reference): every X-Ray endpoint, grouped


---

# Install the SDK (/tracking/install-sdk)



The fastest, least error-prone way to install is to let your coding agent do it. It detects your framework, provisions the tracker, installs `@hellyeah/x-ray`, places the snippet in the correct entry point, and instruments a first conversion. Reach for the manual snippets only when you'd rather wire it in yourself.

<Tabs items="[&#x22;Agent&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Agent">
    **Recommended.** One command installs the tracker skill so your coding agent can wire X-Ray into your repo:

    ```bash
    hellyeah skills add tracker --global --yes
    ```

    Target a specific agent with `--agent`:

    ```bash
    hellyeah skills add tracker --global --agent claude-code
    hellyeah skills add tracker --global --agent cursor
    ```

    Then ask your agent to "add Hellyeah tracking to this project." The skill carries the rest: it detects your framework, provisions a tracker, installs `@hellyeah/x-ray`, places the snippet in the right entry point, and instruments a first conversion. It shows you the diff before writing and stops for your review. Works with Claude Code, Cursor, Codex, Windsurf, and other agents that can edit files and run shell commands.

    The Manual tab is exactly what it places, if you'd rather wire it in yourself.
  </Tab>

  <Tab value="Manual">
    Install the package:

    ```bash
    npm i @hellyeah/x-ray
    ```

    Pick the snippet that matches your stack. Replace `your-website-id` with the `trackerId` returned by `hellyeah tracker create` or `hellyeah tracker state`.

    ### Vanilla script tag [#vanilla-script-tag]

    Drop this in your `<head>`.

    ```html
    <script
      async
      defer
      src="https://xray.hellyeahai.com/script.js"
      data-website-id="your-website-id"
    ></script>
    ```

    Autocapture for pageviews, clicks, form submits, and outbound links starts immediately.

    ### React / Next.js [#react--nextjs]

    ```tsx
    import { Analytics } from "@hellyeah/x-ray/next";

    export default function Layout({ children }) {
      return (
        <>
          <Analytics websiteId="your-website-id" />
          {children}
        </>
      );
    }
    ```

    Use this in your root layout (App Router) or `_app.tsx` (Pages Router).

    ### Remix [#remix]

    ```tsx
    import { Analytics } from "@hellyeah/x-ray/remix";

    export default function App() {
      return (
        <html>
          <body>
            <Analytics websiteId="your-website-id" />
            <Outlet />
          </body>
        </html>
      );
    }
    ```

    ### Vue / Nuxt [#vue--nuxt]

    ```ts
    // Nuxt: plugins/x-ray.client.ts
    import { injectAnalytics } from "@hellyeah/x-ray/nuxt";

    export default defineNuxtPlugin(() => {
      injectAnalytics({ websiteId: "your-website-id" });
    });
    ```

    ```vue
    <!-- Vue: src/App.vue -->
    <script setup lang="ts">
    import { Analytics } from "@hellyeah/x-ray/vue";
    </script>

    <template>
      <Analytics website-id="your-website-id" />
      <!-- the rest of your app -->
    </template>
    ```

    ### Svelte / SvelteKit [#svelte--sveltekit]

    ```svelte
    <script lang="ts">
      import { injectAnalytics } from "@hellyeah/x-ray/svelte";
      import { onMount } from "svelte";

      onMount(() => {
        injectAnalytics({ websiteId: "your-website-id" });
      });
    </script>
    ```

    ### Astro [#astro]

    ```astro
    ---
    // src/layouts/Base.astro
    ---
    <html>
      <head>
        <script>
          import { inject } from "@hellyeah/x-ray/astro";
          inject({ websiteId: "your-website-id" });
        </script>
      </head>
      <body><slot /></body>
    </html>
    ```

    ### Node / Bun server [#node--bun-server]

    For server-side events (webhooks, background jobs, API routes), use the batching client:

    ```ts
    import { XRay } from "@hellyeah/x-ray/server";

    const xray = new XRay("your-website-id", {
      host: "https://xray.hellyeahai.com",
      flushAt: 20, // batch size before auto-flush
      flushInterval: 10_000, // ms between auto-flushes
    });

    xray.track("purchase", {
      revenue: 49.99,
      currency: "USD",
      distinctId: "user-123",
    });

    // Serverless: bypass queue, send immediately
    await xray.trackImmediate("purchase", { revenue: 49.99 });

    // On shutdown: flush remaining events
    await xray.shutdown();
    ```
  </Tab>
</Tabs>

## Quick-start tracking [#quick-start-tracking]

Once installed, use `track()` and `identify()` from anywhere:

```ts
import { track, identify } from "@hellyeah/x-ray";

track("signup_click", { plan: "pro" });
identify("user-123", { email: "user@example.com" });
```

You can also use declarative tracking: any element with `data-hy-event="signup_click"` fires the event on click, with optional `data-hy-prop-*` attributes for properties.

## Next [#next]

* [Track events](/tracking/track-events): custom and conversion events
* [Identify users](/tracking/identify-users): hashed-PII identity


---

# Privacy (/tracking/privacy)



X-Ray is built for ad attribution and conversion reporting, not personal profiling. The defaults stay close to what you need to optimize a campaign and nothing more.

## Cookies [#cookies]

The default tracker uses a single first-party identifier to distinguish visits, set on the same origin as your site. It does not set third-party cookies, fingerprint the browser, or read personal data.

Most deployments do not need a cookie banner for X-Ray's default flow. If your jurisdiction or consent policy requires opt-in for analytics, mount the SDK only after the visitor consents.

## What we collect [#what-we-collect]

* Pageviews, click events, form submits, outbound links, web vitals (autocapture)
* Custom and conversion events you send through `track()`
* Click IDs (`gclid`, `fbclid`, `msclkid`, `ttclid`, `li_fat_id`, `twclid`, `gbraid`, `wbraid`) and `utm_*` params on first visit, retained for 90 days
* Identifiers passed to `identify()`. Email and phone are SHA-256 hashed before storage, and raw contact details are not stored.

## GDPR [#gdpr]

For sites under GDPR, BIPA, or similar regimes:

* Disclose the 90-day attribution window in your privacy notice.
* List the categories above (events, click IDs, hashed identifiers).
* Avoid sending personal data in custom event properties.
* Honor consent: don't call `inject()` until the visitor has accepted analytics.

## Data location [#data-location]

X-Ray events are stored in Hellyeah-managed infrastructure and used only to power your campaign reports and the conversion signals sent to ad platforms.

## Reach out [#reach-out]

Compliance questions or DPA requests: contact us via the link on hellyeahai.com.


---

# Track Events (/tracking/track-events)



X-Ray autocaptures pageviews, clicks, form submits, outbound links, and web vitals. Add explicit tracking for conversion events that should feed campaign reports and ad platform postbacks.

## Conversion events [#conversion-events]

Use the `cv` constant for type-safe conversion names. Import it from `@hellyeah/x-ray` in client code or `@hellyeah/x-ray/server` in server code.

```ts
import { cv, track } from "@hellyeah/x-ray";

track(cv.leadSubmit, {
  plan: "pro",
});

track(cv.purchase, {
  revenue: 49.99,
  currency: "USD",
});
```

`cv.purchase` sends `"cv_purchase"`, `cv.leadSubmit` sends `"cv_lead_submit"`, and the typed constants prevent typos that would otherwise break ad platform postbacks.

## Server events [#server-events]

Use the server import for webhooks, background jobs, and API routes.

```ts
import { XRay, cv } from "@hellyeah/x-ray/server";

const xray = new XRay("your-website-id");

await xray.trackImmediate(cv.purchase, {
  revenue: 49.99,
  currency: "USD",
  distinctId: "user-123",
});
```

Conversion events appear in campaign reports and help Hellyeah understand what happened after the ad click.

## Custom events [#custom-events]

Custom events are available for product-specific behavior that is not a conversion. Keep them secondary to typed conversion events.

```ts
import { track } from "@hellyeah/x-ray";

track("pricing_viewed", {
  plan: "pro",
});
```

## Naming rules [#naming-rules]

* Use `snake_case`
* Keep names stable
* Use `cv` constants for business outcomes
* Put details in properties instead of creating too many event names