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 launch reserves budget against the wallet balance. The launch command requires --yes to authorize the wallet debit. If the launch fails or you cancel a campaign within 48 hours, unspent cents are refunded back to the wallet automatically.

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 turns an approved campaign draft into a live Google Ads campaign. The API snapshots the selected creatives, reserves budget against your wallet, applies the target 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. Brand colors, logos, business context, audience defaults, and tone 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.