@koda-sl/baker-cli 0.233.0 → 0.235.0

package/README.md

@@ -796,6 +796,13 @@ baker ads meta activities --account-id act_123 --days 7
 # "Which Page should this ad run from?"
 baker ads meta pages                                                 # Facebook Pages the user manages (tasks shows which can ADVERTISE)
 
+# "What is the lead form collecting, and how many came in?"
+baker ads meta lead-forms --page-id 100635183117758                  # instant forms on a Page + lead counts
+baker ads meta lead-forms --page-id 100635183117758 --full           # also each form's questions
+baker ads meta leads --form-id 987654321 --since 2026-08-01 --until 2026-08-31
+baker ads meta leads --form-id 987654321 --after <nextCursor>        # results are PAGED — follow the cursor
+baker ads meta leads --form-id 987654321 --full                      # raw contact details (CRM hand-off only)
+
 # "What are we running right now?"
 baker ads meta campaigns --account-id act_123                        # ACTIVE only by default
 baker ads meta ads --account-id act_123 --all-statuses               # widen to everything
@@ -818,6 +825,9 @@ baker ads meta pixels --account-id act_123
 baker ads meta pixels --pixel-id 9988 --stats --days 7
 ```
 
+**Instant-form leads** — `leads` returns **one page** plus a `nextCursor`; a response carrying one is not the whole set, so follow it before quoting any total. Email and phone answers come back masked unless `--full`. Both commands need Meta lead ads switched on for the company (`pages_manage_ads` + `leads_retrieval`, granted at connect time — a company switched on after connecting must reconnect Meta first); each says which of the two is missing.
+
+
 #### Staged writes (`baker ads meta campaigns|adsets|ads|creatives|audiences|media|draft`)
 
 Meta writes mirror the Google/LinkedIn model: they **never hit the Graph API when you run them**. Each op is validated at stage time (field shapes, budget rules, page/Instagram identity ownership, CBO/ABO exclusivity, status-transition legality), shows in the dashboard chat as a pending Meta change, and applies only when the chat is published. Meta has no atomic batch mutate, so ops apply **sequentially** on publish — one failure skips its dependents but the publish completes.
@@ -1155,7 +1165,7 @@ Each finding: `{id, area, check, status, severity, evidence, fix: {explanation,
 
 GA4 commands for multi-channel audits **and** for configuring what the property measures. Playbook-aligned report presets, property health audits, free-form Data API queries, and staged Admin API writes.
 
-Reads (`properties`, `config`, `audit`, `query`) happen immediately. Writes (`key-event`, `custom-dimension`, `custom-metric`, `custom-event`, `data-retention`) are **staged** onto the chat, reviewed in the dashboard's Analytics tab, and applied when the chat completes — at which point they take effect on the property immediately. There is no simulated mode and no undo.
+Reads (`properties`, `config`, `audit`, `query`) happen immediately. Writes (`key-event`, `custom-dimension`, `custom-metric`, `custom-event`, `data-retention`, `audience`, `property`, `ads-link`, `enhanced-measurement`) are **staged** onto the chat, reviewed in the dashboard's Analytics tab, and applied when the chat completes — at which point they take effect on the property immediately. There is no simulated mode and no undo.
 
 A Google Analytics connection made before writes shipped is read-only and every write command refuses with a message saying to reconnect. `baker ga4 config` reports `canWrite`.
 
@@ -1277,12 +1287,31 @@ baker ga4 custom-event delete 7
 # How long data is kept (months: 2, 14, 26, 38, 50 — over 14 needs Analytics 360)
 baker ga4 data-retention set --event-data 14 --user-data 14
 
+# An audience — a saved group of users, for retargeting and analysis
+baker ga4 audience create --json '{"displayName":"Started demo without finishing","description":"Triggered demo_started and never submitted the demo form","membershipDurationDays":90,"filterClauses":[{"clauseType":"INCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS","filterExpression":{"eventFilter":{"eventName":"demo_started"}}}},{"clauseType":"EXCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS","filterExpression":{"eventFilter":{"eventName":"demo_form_submitted"}}}}]}'
+baker ga4 audience update 8813 --json '{"displayName":"Started demo without finishing (90d)"}'
+baker ga4 audience archive 8813
+
+# The property's own settings — the industry decides its benchmarking cohort
+baker ga4 property set --industry TECHNOLOGY
+
+# The automatic web-stream events — no tag to add
+baker ga4 enhanced-measurement set --scrolls true --outbound-clicks true --file-downloads true
+baker ga4 enhanced-measurement set --site-search true --search-parameters "q,s,search,query,keyword"
+
+# Link to Google Ads — what makes audiences targetable and key events importable
+baker ga4 ads-link create --customer-id 123-456-7890
+baker ga4 ads-link update L1234 --ads-personalization false
+baker ga4 ads-link delete L1234
+
 # Several definitions in one call — one read of the property instead of one per definition
 baker ga4 custom-dimension create --json '[{"parameterName":"plan_tier","displayName":"Plan tier","scope":"EVENT"},{"parameterName":"lead_source","displayName":"Lead source","scope":"EVENT"}]'
 ```
 
 Every `create` accepts a JSON array as well as a single object, and stages the whole list in one request (all-or-nothing). Prefer it for bulk work: each stage reads the property's full configuration first, so separate calls multiply that read.
 
+An **audience is permanent once created**: its conditions, membership window and exclusion mode are immutable, so `audience update` takes only a name and a description, and fixing a definition means archiving it and building a replacement that starts with no users. Staging also warns when the property has no Google Ads link, because an audience without one can never be retargeted. `enhanced-measurement` sets the events GA4 collects on a website stream by itself; `--site-search true` requires `--search-parameters`, and staging refuses without them rather than letting the publish fail. `ads-link` is the only GA4 command that reaches outside Analytics — it starts a flow of the client's data between their Analytics property and their Google Ads account, so staging warns and the agent is told to agree it with the user first. `property set` covers the display name and the industry category only — time zone and currency are excluded on purpose, since both re-bucket every future day without reprocessing history. Sequence-based audiences are not supported.
+
 Custom dimensions and metrics are **archived**, not deleted (the slot frees, past data stays); key events and custom events are **deleted**. Neither is reversible from Baker. Because `parameterName` and `scope` are immutable, changing one is an archive plus a create staged on the same chat — the removal applies first and frees the name. `--property-id` is required when more than one property is connected, and one chat stages changes for one property; `--data-stream` is required for a custom event when the property has more than one website stream.
 
 ---