feat(contacts): --dry-run and --on-conflict on contacts import and import-csv

CHANGELOG.md

@@ -14,12 +14,20 @@ These import changes require `@brew.new/sdk` 13.3.0 or newer, which adds
 - **`contacts import`** (`POST /v1/contacts/import`): bulk-import up to 1000
   contacts from a JSON file (an array, or `{ "contacts": [...] }`) or stdin as
   one batch in Brew's Import History. Takes `--file-name`, `--validate` and
-  `--consent-source`, and prints the batch's `importId`. A JSON object body
+  `--consent-source`, and prints the batch's `importId` (none on a `--dry-run`). A JSON object body
   keeps its own `validate`, `consent` and `fileName`; a flag overrides them
   only when given.
 - `contacts import-csv` names its batch in Import History: `--file-name`, else
   a `fileName` in `--input`, else the `--file` name. Both imports return
-  `importId`.
+  `importId`, except on a `--dry-run`.
+- `contacts import` and `contacts import-csv` take `--dry-run` (print what
+  the import would do and write nothing: no contacts, fields or Import History
+  batch, no `importId`) and `--on-conflict upsert|skip` (`skip` creates
+  missing contacts and leaves existing ones unchanged, counted as skipped
+  with a `CONTACT_EXISTS_SKIPPED` warning). The terminal summary of a dry run
+  reads "Dry run of <file> — nothing was written: N to add, …" (or "Dry run
+  — nothing was written: …" without a file name). These flags require the
+  matching API deployment.
 - On a terminal, `contacts import` and `contacts import-csv` print the API's
   submitted total and outcome counts, plus failed rows and warnings with
   available row, email and field details. `--json` preserves the API envelope.
@@ -33,6 +41,12 @@ These import changes require `@brew.new/sdk` 13.3.0 or newer, which adds
 - `contacts upsert-many` says what it is for: up to 1000 contacts per call
   (its summary said 100) with no Import History entry, for recurring syncs.
 
+
+### Fixed
+
+- `flows get` takes a `<domain>/<kind>` slug from `flows list` (one send
+  stream's flow) and a `--kind` flag for a bare-domain slug.
+
 ## 0.17.0
 
 Requires `@brew.new/sdk` `^13.0.0`. This is a minor release because it adds

docs/commands/README.md

@@ -463,12 +463,15 @@ Bulk-import up to 1000 contacts from a JSON file or stdin as one Import History
 - `--file-name <name>` — Name the batch in Brew's Import History (default: the --file name)
 - `--validate` — Deliverability-check every imported address (2 credits per address)
 - `--consent-source <source>` — Default marketing consent record for rows without their own: api, form or import
+- `--dry-run` — Show what the import would do and write nothing (no contacts, fields or Import History batch; --validate is skipped and nothing is charged)
+- `--on-conflict <mode>` — upsert (default) updates existing contacts; skip only creates missing ones and leaves existing contacts unchanged (counted as skipped)
 - `--input <json>` — Full JSON request body, or - to read stdin (flags override it)
 - `--idempotency-key <key>` — Idempotency-Key for safe retries (auto-generated otherwise)
 
 ```bash
 brew-cli contacts import --file contacts.json --consent-source import
 cat contacts.json | brew-cli contacts import --file - --file-name crm-export.json
+brew-cli contacts import --file contacts.json --dry-run --on-conflict skip
 ```
 
 ### brew-cli contacts import-csv
@@ -484,13 +487,17 @@ Bulk-import contacts from a CSV file or stdin as one Import History batch (free;
 - `--date-order <order>` — month_first or day_first: how to read dates like 03/04/2026 (a day over 12 in the column wins; default month-first, with a DATE_ORDER_ASSUMED warning)
 - `--validate` — Deliverability checks: up to 100 submitted CSV data rows cost 2 credits/row inline; larger files use background checks when needed, charged per address
 - `--consent-source <source>` — Stamp a marketing consent record on every row: api, form or import (sets the source of a record given in --input)
+- `--dry-run` — Show what the import would do and write nothing (no contacts, fields or Import History batch; --validate is skipped and nothing is charged)
+- `--on-conflict <mode>` — upsert (default) updates existing contacts; skip only creates missing ones and leaves existing contacts unchanged (counted as skipped)
 - `--input <json>` — Full JSON request body, or - to read stdin (flags override it)
 - `--idempotency-key <key>` — Idempotency-Key for safe retries (auto-generated otherwise)
 
 ```bash
 brew-cli contacts import-csv --file contacts.csv
 cat contacts.csv | brew-cli contacts import-csv --file - --mapping Email=email
 brew-cli contacts import-csv --file eu-signups.csv --date-order day_first --consent-source import
+brew-cli contacts import-csv --file contacts.csv --dry-run
+brew-cli contacts import-csv --file contacts.csv --on-conflict skip
 ```
 
 ### brew-cli fields list
@@ -2493,12 +2500,14 @@ Fetch one public email flow by brand domain, with every step (day offset, wait,
 - Route: `GET /v1/flows/{slug}`
 - Class: read
 - SDK: `brew.flows.get(...)`
-- Argument `slug` — The brand domain a `flows list` card carries (e.g. brew.new)
+- Argument `slug` — The slug a `flows list` card carries: a brand domain (brew.new) or <domain>/<kind> (brew.new/welcome)
 - `--include <keys>` — Comma-separated expansions: html (each step’s rendered HTML, best-effort per step)
+- `--kind <kind>` — One send stream’s flow for a bare-domain slug (e.g. welcome); a <domain>/<kind> slug already names it
 
 ```bash
 brew-cli flows get brew.new
 brew-cli flows get brew.new --include html --json
+brew-cli flows get brew.new/welcome
 ```
 
 ### brew-cli integrations list