Concepts

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

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

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. One prompt, one plan, one launch. The user says "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:

Confirm brand: business details the agent extracted
Confirm creatives: generated or uploaded assets
Confirm draft: budget, audience, copy, schedule
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

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

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

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.