@koda-sl/baker-cli 0.114.1 → 0.115.0

package/README.md

@@ -653,6 +653,56 @@ baker ads google library search-competitors "crm software" --location uk
 
 ---
 
+### Staged writes (`baker ads google budgets|campaigns|...`)
+
+Write commands **never touch the Google Ads API at stage time**. Each command stages a create/update/pause/resume/remove op against the current chat's draft (`BAKER_CHAT_ID`); the dashboard shows it as a pending "Google Ads" change, and the whole draft applies as one atomic `GoogleAdsService.Mutate` when the chat is published. Feature-flagged per company (`companies.googleAdsWriteEnabled`) — off by default = a fully simulated publish with zero real API calls.
+
+Reference not-yet-created resources with `g_temp_*` refs returned by earlier `create` commands (they map to Google's temporary negative-ID resource names inside one atomic batch).
+
+```bash
+# Build a Search campaign bottom-up, chaining temp refs
+baker ads google budgets create --customer-id 1234567890 --name "Search budget" --amount 50
+# → { ref: "g_temp_ab12", ... }
+baker ads google campaigns create --customer-id 1234567890 --name "Brand — Search" \
+  --channel-type SEARCH --budget-ref g_temp_ab12 --bidding-strategy MANUAL_CPC
+baker ads google ad-groups create --customer-id 1234567890 --name "Brand terms" --campaign-ref g_temp_<campaign>
+baker ads google keywords add --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> --text "brand name" --match-type EXACT
+# Shared negative keyword list → attach to the campaign
+baker ads google keyword-lists create --customer-id 1234567890 --name "Brand exclusions"
+baker ads google keyword-lists add --customer-id 1234567890 --list-ref g_temp_<list> --text "free" --match-type BROAD
+baker ads google keyword-lists attach --customer-id 1234567890 --campaign-ref g_temp_<campaign> --list-ref g_temp_<list>
+
+# Batch keywords — one command stages the whole set as ONE request (up to 500)
+baker ads google keywords add --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> \
+  --text "brand name, brand shop:PHRASE, brand store" --match-type EXACT
+baker ads google keyword-lists add --customer-id 1234567890 --list-ref <list-id> --file negatives.txt
+# negatives.txt: one keyword[:MATCH_TYPE] per line; blank lines and "# comments" are skipped
+# Responsive search ad
+baker ads google ads create --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> \
+  --headlines "Fast Widgets,Buy Online,Free Shipping" --descriptions "Best widgets around.,Ships tomorrow." \
+  --final-url https://example.com
+# Responsive display ad — images are fields on the ad; register each image as an asset first (returns a g_temp_* ref)
+baker ads google assets create --customer-id 1234567890 --file '{"type":"image","imageId":"<baker_image_id>","name":"Hero"}'
+baker ads google ads create --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> --format responsiveDisplay \
+  --headlines "Come back and save" --long-headline "Finish signing up and get 20% off" \
+  --descriptions "Fast setup, no card required" --business-name "Acme" --final-url https://example.com \
+  --marketing-images g_temp_<img_landscape> --square-marketing-images g_temp_<img_square> --logo-images g_temp_<img_logo>
+
+# Review / undo staged changes
+baker ads google draft list                  # readable campaign ▸ ad group ▸ ad tree + completeness advisories
+baker ads google draft list --json           # raw JSON envelope for scripting
+baker ads google draft remove g_temp_ab12    # cascades to dependents
+baker ads google draft clear
+```
+
+Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remove), `negative-keywords`, `keyword-lists`, `ads`, `assets`, `audiences`, `conversions`, `bidding-strategies`, `labels`, `campaign-criteria`, and `draft`. Amounts are in major currency units (converted to micros). Money/bids: `--amount`, `--cpc-bid`, `--target-cpa` take major units; `--target-roas` a ratio. Less-common ops accept a `--file <payload.json>` (flags override file keys). Updates target a resource name or bare id as the positional argument; a target that names an op staged earlier **amends it in place**.
+
+**Reviewing the draft** — `baker ads google draft list` renders everything you've staged as a grouped campaign ▸ ad group ▸ ad tree (with the simulated/live mode banner and non-blocking completeness advisories), the CLI counterpart to the dashboard's Google Ads tab. Pass `--json` for the raw envelope. Aim for a fully built campaign — 2–4 ad groups, ≥5 keywords each, 2–4 RSAs with 8–12 headlines, ≥4 sitelinks / ≥3 callouts / ≥1 structured snippet, and ≥1 shared negative list; the advisories flag what's still thin.
+
+**Batch keyword adds** — `keywords add`, `negative-keywords add`, and `keyword-lists add` take a whole batch in one command: comma-separate `--text` entries and/or pass `--file <list.txt>` (one keyword per line). A `:EXACT`/`:PHRASE`/`:BROAD` suffix per entry overrides the `--match-type` default. Batches stage all-or-nothing as one request (limit 500); each keyword still lands as its own draft op, so it stays individually removable/amendable.
+
+---
+
 ### Caching
 
 Google Ads data is cached at two levels: