@getbrevo/cli 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,214 @@
 # @getbrevo/cli
 
+## 2.1.0
+
+### Minor Changes
+
+- e6d72f5: `brevo app update` is replaced by `brevo app upload`, `brevo app scaffold` can set up a
+  directory for an app you already have, `app-config.json` moves to a new shape,
+  `brevo <command> --help` prints that command's own usage, and `--json` now produces output
+  on failure paths.
+
+  ## `brevo app update` → `brevo app upload` (BEX-250)
+
+  `upload` takes only `--yes` and `--json`. The edit flags (`--app-id`, `--name`,
+  `--redirect-uri`, `--scope`, `--logo-uri`) are gone — edit `app-config.json`, then upload.
+
+  It always fetches the app's remote state and shows a local-vs-server diff before pushing,
+  including under `--yes` (skips the prompt only) and `--json`. No differences means exit `0`,
+  "already up to date", and no network push. Otherwise the whole local file is pushed and the
+  server-confirmed state written back. `distribution_type` is immutable after `app create`; a
+  changed value is refused locally.
+
+  `app update` stays registered but hidden, and answers with a message naming its replacement
+  (reachable with any removed flag, stray args, `--help`, or `brevo app help update`, and with
+  no login). Nothing is forwarded or uploaded; it exits `1`.
+
+  **Migrating:** `brevo app scaffold --app-id <id>`, edit `app-config.json`, `brevo app upload`.
+
+  ## `brevo app scaffold` gains a bootstrap mode
+
+  `scaffold` now picks its mode from whether the current directory holds an `app-config.json`.
+  With one, it adds a feature to the linked app. Without one it _bootstraps_ — sets the
+  directory up for an app that already exists — the successor to `brevo app update --app-id`.
+  - `--app-id <id>` fetches the app, writes `app-config.json` plus the base files, then
+    continues into the feature flow.
+  - Interactively with no config and no flag, it asks _"Set up a project for an app you already
+    have?"_ (default yes) and shows an app picker, so recovery no longer needs the app's ID.
+    Declining exits `0`. Under `--json` or off a TTY the usual no-config error is raised, so
+    scripts are unaffected.
+  - A bootstrap also asks for an output directory (defaulting to the app name as a slug),
+    creates it, and reports `cd <dir>` as the first next step; answer `.` to stay put. The
+    project is written and shown _before_ the feature question, so declining still leaves a
+    usable project.
+
+  Bootstrapping refuses three cases before any network call, each of which previously produced
+  a silently wrong project: a directory **inside** an existing app project (which used to nest
+  a second config, after which `upload` pushed the wrong app); `--app-id` naming a **different**
+  app than the directory is linked to; and an output directory that is **already another app's
+  project** (where answering _Merge_ left that app's config in place while writing this app's
+  credentials beside it).
+
+  `scaffold` also asks before reusing existing feature files — **Overwrite / Merge / Cancel**
+  (default Merge) — and a new `--overwrite` flag forces a full overwrite without prompting.
+
+  **Fixed:** bootstrapping into a directory that already holds a project for the _same_ app
+  wrote nothing and reported success. It is now treated as the refresh it is: drift is listed,
+  you confirm, the file is rewritten.
+
+  **Fixed:** `brevo app scaffold --json` could block on a prompt and hang CI. It now never
+  prompts — each case reports `{ "cancelled": true, "reason": "...", "diffs": [...] }`.
+
+  ## `brevo app create`
+
+  Creation is split from feature scaffolding. `create` writes only the base project
+  (`app-config.json`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`); the OAuth
+  test-server code is now a feature, scaffolded when _"Scaffold the Test OAuth App?"_
+  (default yes) is accepted. Non-interactive runs stay base-only — add the code later with
+  `brevo app scaffold`.
+
+  `create` now hard-errors if `app-config.json` already exists, resolves its target directory
+  before creating the app, says where files are landing, and adds a `cd <dir>` step to
+  _Next steps_ when they land elsewhere. The logo URL is asked right after the app name;
+  `--logo-uri` and non-interactive runs are unchanged. Neither command asks _"What feature do
+  you want to scaffold?"_ any more — the CLI ships one feature; the picker returns
+  automatically if a second is added.
+
+  Fixed in `create`:
+  - `Client ID: undefined` — the create response nests OAuth fields under `auth`, which
+    dropped `Redirect URL n:` lines and omitted `clientId` / `redirectUri` from `--json`. The
+    response is now flattened in one place, tolerating both shapes.
+  - A failed read-back no longer destroys a successful create. A `404` on that one read now
+    falls back to the create response and completes with a warning instead of exiting non-zero
+    while the app sits on the server.
+  - No stray directory is left behind when create fails — the directory _decision_ still comes
+    first, but nothing is written until there is provably an app to write it for.
+  - The file count no longer reads `(0 files)` above a file tree; it reports `created (5 files)`,
+    `already in place (5 files, nothing rewritten)`, or `created (2 of 5 files written)`.
+  - Choosing Overwrite/Merge on _"Directory already exists"_ now says `Moving into <dir>...`
+    rather than contradicting the answer with `Creating <dir> and moving into it...`.
+
+  ## `app-config.json` shape
+
+  Backward compatible on read, migrated on the next write-back (`upload`, `app start`'s URL
+  registration, `credentials`, or `scaffold`):
+  - `auth.redirectUrls` → **`auth.redirectUris`**, matching the wire key `redirect_uris`. The
+    old key is still read; the new one wins if both are present.
+  - A legacy top-level `distribution`, and the interim `auth.type`, become **`distribution_type`**.
+  - New read-only top-level **`version`**, tracking the app-store API's version field.
+  - `cliVersion`, `permittedUrls`, `support` and `auth.type` are dropped — nothing read them.
+
+  **Downgrade caveat:** older releases read only `redirectUrls`, so a migrated file reads to
+  them as having no redirect URLs. That is loud and harmless in `app update`, but **`app start`
+  costs you something**: seeing an empty list it offers to register
+  `http://localhost:<port>/auth/callback` and, on yes, pushes that single URL as the app's whole
+  `redirect_uris` — dropping every real one, silently. Upgrade the lagging CLI, or keep both
+  keys as a stopgap; if it already happened, restore the list and `brevo app upload`.
+
+  `brevo app credentials` backfills a legacy config toward the current shape when its `appId`
+  matches the app being inspected, filling a missing `version` / `distribution_type` from the
+  server without overwriting existing values — so projects that are never uploaded converge too.
+
+  ## Help, `--json`, and debugging
+  - **`brevo <command> --help` prints that command's own usage, arguments, flags and examples.**
+    Subcommands previously rendered the root help screen, which never named the flags being
+    looked for. The root screen is unchanged.
+  - **`--json` now applies on failure.** Commands other than `whoami` and `logout` exited
+    non-zero with nothing on stdout. Failures now write one `{"error": {...}}` document carrying
+    `name`, `message`, `exitCode`, plus `statusCode` and (when classified) `code`. The
+    human-readable message still goes to stderr, so stdout stays exactly one parseable document.
+  - **`brevo app list` shows a `Version:` line** and includes `version` in `--json`. It is also
+    hardened against `redirect_uris: null` / `scopes: null` from the list endpoint, which used to
+    end the listing part-way with `Cannot read properties of null (reading 'length')`; the same
+    dereference is fixed in `app credentials`.
+  - **`--debug` logs the request body** before the request goes out, alongside the response —
+    same `<METHOD> <path>`, same redaction. Nothing changes without `--debug`.
+
+  ## Output
+  - **Boxed output wraps instead of shredding itself.** `printBox` sized itself to its longest
+    line and let the terminal wrap the overflow without the frame. Lines are now wrapped before
+    the frame is drawn — on a word where possible, mid-string where not — with continuation rows
+    indented under their label and colour carried across. Piped output falls back to 80 columns.
+  - **Selection prompts are indented into the CLI's output gutter**; `list` and `checkbox`
+    options used to render two columns left of every other line. Numbered app pickers are
+    unchanged.
+  - **Fixed:** the first row of a printed file tree was indented two columns deeper than the rest.
+  - **The logo-URL prompt fits 80 columns** — `App logo URL (optional — leave blank to skip):`,
+    with the example URL moved to the validation error.
+
+  ## Request payloads
+
+  `POST /v3/app-store/apps` now carries OAuth fields in the same `auth: { scopes, redirect_uris }`
+  block the upload endpoint takes, and upload's version field is renamed `app_version` →
+  `version`. `cli_version` and `source: 'cli'` are no longer sent in either body — both were
+  outside the declared contract, upload rejects unknown keys with a `400`, and the caller is
+  identified by a structured `User-Agent` (`brevo-cli/<version> (<os>; auth=<method>)`).
+
+  ## An expired session is reported before the prompts (BEX-341 follow-up)
+
+  `brevo app create` could ask every question and only then report ``Your session has expired.
+Run `brevo login` ``, discarding all of it: a refresh token the login service _refuses_ was
+  treated like a transient network failure and swallowed.
+
+  A refused token is now terminal — stored credentials are cleared and the expiry is reported
+  from the pre-command hook, before the first prompt. Failures that say nothing about the
+  session (timeout, `5xx`, unwritable credentials file) are still swallowed and never block a
+  command. The token is also re-checked before each authenticated request rather than once at
+  startup, and if a session dies mid-flow `app create` offers to log you back in and re-sends
+  the answers you already gave (interactive terminals only). Exit codes and error text are
+  unchanged.
+
+  ## The legacy `all` OAuth scope is refused on upload (BEX-214)
+
+  `brevo app upload` now stops when `auth.scopes` still contains the deprecated catch-all `all`
+  and explains the migration: replace it with the specific scopes your integration uses, list
+  them with `brevo app available-scopes`, then upload. `brevo app start oauth` refuses the same
+  config with the same guidance, `brevo app list` tags an affected app, and `brevo app scaffold`
+  writes granular scopes.
+
+  The refusal is local — no round trip, nothing pushed. An app already holding `all` on Brevo is
+  untouched until you upload a replacement list; the upload diff then labels it as a migration.
+
+  ## Other fixes
+  - **`auth.scopes` written as a single string is read correctly.** A hand-edited
+    `"scopes": "contacts:read, contacts:write"` was documented as normalized on read and was
+    not — the splitter was only reached for arrays, so the upload validator iterated the string
+    one character at a time and rejected the run with `Invalid scope: ":"`. Strings are now split
+    on commas and whitespace, exactly as over-long array entries always were.
+  - **`app credentials` / `app delete` no longer open an app picker they cannot draw.** Their
+    `--app-id` fallback was not gated on the run being interactive, so under `--json` or off a
+    TTY it printed its choice list to **stdout** and then aborted with
+    `ERR_USE_AFTER_CLOSE: readline was closed`. Both now refuse up front, before any network
+    call, naming the exact command to run and exiting `1`; `--json` gets the usual error
+    envelope. Interactive runs are unchanged. `app delete` is the consequential one — a scripted
+    delete that appeared to rely on the picker was never selecting anything.
+
+- 67390da: Take the update banner's message from the Brevo app-store service, and let it block a CLI version that can no longer be supported.
+
+  Whether an update banner appears is unchanged: the CLI still checks the npm registry, compares against its own version, and applies the same soft-notice and force-update rules. What changed is the first line of that banner, which now comes from `GET /cli/info` and is rendered in red above the box. The box's own contents are untouched.
+
+  That endpoint is called on the app-store service **directly**, not through the v3 API gateway, and needs no API key — so the notice still renders while logged out, mid-`login`, or with expired credentials, which is exactly when a stale CLI is most likely to be the real problem. `BREVO_APP_STORE_URL` overrides the base URL for non-production testing.
+
+  The response may also carry `"is_blocked": true`. When it does, every command except `--help` / `--version` prints the banner to stderr and exits `1` without running, letting a broken CLI version be stopped without shipping a new release. This is deliberately **not** silenced by `BREVO_NO_UPDATE_NOTIFIER=1`, `--no-update-notifier`, CI, or a non-TTY — those suppress a _notice_, and a suppressed banner must never mean a suppressed block.
+
+  Because a block has to prevent a command rather than report on it afterwards, the call now runs once before the command instead of after it. The result is cached at `~/.brevo/cli-info-cache.json` for **15 minutes**, keyed to the running CLI version, so a healthy fleet of invocations doesn't call the app-store service on every single command — revised wording and a new block reach users within minutes rather than after the old 12h npm-style TTL, and an upgrade always gets a live check regardless of the cache's age. A failed call never overwrites a good cache entry.
+
+  It fails open throughout. A timeout, a non-2xx, HTML from a gateway, or an unparseable body all leave the CLI behaving exactly as before — the banner falls back to local wording and nothing is blocked. Only a literal `true` blocks, so an outage can never lock anyone out. The endpoint is fetched outside the authenticated API client, so a 401 from it cannot reach the re-auth handler or clear stored credentials, and the returned text is control-character stripped, flattened to one line, and clamped before display.
+
+  Also show the update notice when a command fails. Previously the banner only printed on the success path, so anyone whose command errored — including the auth errors most likely to be fixed by upgrading — never saw that a newer CLI existed. The banner now prints after the error message on stderr, keeping the command's own exit code, and `notifyUpdate` is idempotent so runs that already showed it up front (`--help`, `app init`, `app create`) don't print it twice. A Ctrl-C abort still exits immediately without waiting on the check.
+
+  The npm registry check backing the soft-notice/force-update gate (`~/.brevo/update-check.json`) moves from a 24h TTL to **12h**, so a newly-published version reaches users about twice as fast.
+
+### Patch Changes
+
+- bcfc3c1: Fix two ways the update banner could show local wording when the app-store service had wording of its own.
+
+  **`--help` and `--version` never asked.** They are exempt from the `is_blocked` gate so a blocked CLI can still say what version it is — but that was implemented by skipping the whole `/cli/info` call, which discarded the message along with the verdict. Both still render an update banner, so the two commands people most often run to check their version were the only ones that could never explain why the version mattered. The exemption now covers the block alone: they fetch the wording, show it, and still exit `0` no matter what `is_blocked` says.
+
+  **The 15-minute cache ignored which service the answer came from.** The entry was keyed on `cliVersion` and `lastChecked` only, but the base URL is overridable per-invocation via `BREVO_APP_STORE_URL`, so two runs against different environments shared one entry — whichever was hit first answered for both until the TTL expired. The symptom was badly misleading: pointing at staging rendered the message production had returned moments earlier and vice versa, so the CLI and a direct `curl` disagreed, and which environment looked broken depended only on the order the two were run in. `baseUrl` is now part of the key. An entry written before the field existed fails the shape check and is treated as a miss, so an upgrade re-fetches once rather than serving a stale answer.
+
+  Neither changes what blocks, what fails open, or any exit code.
+
 ## 2.0.2
 
 ### Patch Changes

package/README.md

@@ -5,7 +5,7 @@ Command-line tool to create, manage, and test [Brevo](https://www.brevo.com/) OA
 > 📖 Full command and option documentation: **[Brevo CLI reference](https://developers.brevo.com/docs/cli-reference)**
 
 > [!WARNING]
-> **Upgrade to v2.0.0.** All versions from **1.1.1** up to (but not including) **2.0.0** should be migrated to **2.0.0**. The `2.0.0` release introduces **breaking changes**, so some CLI commands may not work as expected on older versions.
+> **Upgrade to the latest released version.** All versions from **1.1.1** up to (but not including) **2.0.0** should be migrated to at least **2.1.0**. The `2.0.0` release introduced **breaking changes**, so some CLI commands may not work as expected on older versions. **`2.1.0` and above** also carry further `app-config.json` migrations (e.g. legacy `auth.redirectUrls` → `auth.redirectUris`) that are applied automatically the next time the CLI writes your config (`brevo app upload`, `brevo app start`, …).
 >
 > Upgrade with `npm install -g @getbrevo/cli@latest` (or `yarn global add @getbrevo/cli@latest`, or `brew upgrade brevo`), then confirm with `brevo --version`.
 
@@ -93,16 +93,19 @@ Run `brevo --help` or `brevo <command> --help` for full command and option lists
 | `brevo logout` | Clear stored credentials (`--force` to skip confirmation) |
 | `brevo whoami` | Show the authenticated user |
 | `brevo app init` | Guided setup — login, create app, and scaffold in one go |
-| `brevo app create` | Create an OAuth app (`--name`, `--distribution private\|public`, repeatable `--redirect-uri`, `--logo-uri`) |
-| `brevo app list` | List OAuth apps in your account |
+| `brevo app create` | Create an OAuth app (`--name`, `--distribution private`, repeatable `--redirect-uri`, `--logo-uri`) |
+| `brevo app list` | List apps in your account |
 | `brevo app credentials` | Show client ID and secret (`--app-id`, `--reveal-secret`) |
-| `brevo app update` | Update app name, redirect URLs, or logo (`--app-id`, `--name`, repeatable `--redirect-uri`, `--logo-uri`, `--yes`) |
+| `brevo app upload` | Push `app-config.json` to Brevo after showing a local-vs-server diff (`--yes`) |
 | `brevo app delete` | Delete an app (`--app-id`, `--force`) |
-| `brevo app scaffold` | Generate starter code for an app (`--app-id`) |
+| `brevo app scaffold` | Add a feature to the app in the current directory, or set an empty directory up for an app you already have — picked interactively, or named with `--app-id` (`--overwrite`, `--json`) |
 | `brevo app start` | Run a scaffolded feature locally (e.g. `brevo app start oauth --port 3000`) |
+| `brevo app available-scopes` | List the OAuth scopes the IdP supports (`--web` opens the catalog in a browser) |
 
 Most commands require a successful `brevo login` first, except authentication/help flows (`brevo login`, `brevo logout`, `brevo app init`, `--help`). Every command accepts `--json` for machine-readable output.
 
+The table above is the complete command surface of a published release. Features that aren't live on the Brevo platform yet aren't built into the package — `brevo --help` always lists everything the binary can do, so there is nothing hidden behind a flag or an environment variable.
+
 ### Browser login
 
 `brevo login` defaults to a browser-based sign-in. The CLI starts a temporary loopback server, opens your browser to the Brevo CLI login service, and stores the returned tokens in `~/.brevo/credentials.json`. Access tokens refresh automatically on expiry.

package/agent-context/AGENTS.md

@@ -3,6 +3,18 @@
 
 This project uses the [Brevo Developer CLI](https://www.npmjs.com/package/@getbrevo/cli) (`brevo` binary) to manage Brevo OAuth applications.
 
+## `brevo --help` is the source of truth
+
+Brevo features that haven't been released are **not built into the published CLI at all** — not as hidden commands, not behind a flag or an env var. `brevo --help` and `brevo app --help` list everything the binary can do. Treat that as the complete surface and build from it.
+
+What this means in practice:
+
+- **If a command isn't in `--help`, it doesn't exist here.** Invoking it gives Commander's `unknown command` and exit `1`. That is a final answer, not a transient failure and not a permissions problem — there is no flag, config edit, account setting, or environment variable that reveals it. Don't retry, don't hunt for an alternative route, and don't tell the user to request access. Say the feature isn't available in this CLI and offer the nearest thing that works.
+- **Don't act on a command you remember rather than one you can see.** Your training data may include commands from a newer or unreleased build of this CLI. `--help` in the current session is the only reliable source, and the table below documents only what a published build ships.
+- **A flag can be rejected even when its command exists.** `--distribution` is a real flag, but a value tied to an unreleased feature is refused with *"That command is not available yet. It is part of a Brevo feature that has not been released."* Same rule: it's final. Use `--distribution private`.
+
+The Brevo API enforces the same boundaries independently, so nothing is gained by routing around the CLI — a hand-rolled `curl` hits the platform's own refusal.
+
 ## AI agents — start here
 
 Pick the path that matches your tooling:
@@ -50,7 +62,7 @@ Don't fall back to raw HTTP against `api.brevo.com` — the `brevo` binary is th
 
 ## When to use it
 
-- Create, list, update, or delete Brevo OAuth apps
+- Create, list, upload changes to, or delete Brevo OAuth apps
 - Scaffold a starter OAuth integration
 - Run a local OAuth test server (`brevo app start oauth`)
 - Inspect or rotate app credentials
@@ -63,12 +75,12 @@ Don't fall back to raw HTTP against `api.brevo.com` — the `brevo` binary is th
 | `brevo logout` | Clear stored credentials (`--force`, `--json`) |
 | `brevo whoami` | Show the authenticated account (`--json`) |
 | `brevo app init` | Guided setup (login, create, scaffold) |
-| `brevo app list` | List OAuth apps (`--json`) |
-| `brevo app create` | Create an app (`--name`, `--distribution`, `--redirect-uri`, `--logo-uri`, `--json`). Only `--distribution private` is available today — `public` is rejected with a "coming soon" error. Defaults to scopes `contacts:read`, `contacts:write`, `crm:read`, `crm:write`. |
-| `brevo app update` | Update name / redirect URLs / scopes / logo (`--app-id`, `--name`, `--redirect-uri`, `--scope` repeatable appends, `--logo-uri`, `--yes`, `--json`) |
-| `brevo app credentials` | Show client ID / secret (`--app-id`, `--reveal-secret`, `--json`) |
-| `brevo app delete` | Delete an app (`--app-id`, `--force`, `--json`) |
-| `brevo app scaffold` | Generate starter OAuth code (`--app-id`, `--json`) |
+| `brevo app list` | List apps (`--json`). Each row names its type. |
+| `brevo app create` | Create an app (`--name`, `--distribution private`, `--redirect-uri`, `--logo-uri`, `--json`). **Pass `--distribution private`** — run `brevo app create --help` for the values this build accepts and don't pass one it doesn't list. Defaults to scopes `contacts:read`, `contacts:write`, `crm:read`, `crm:write`. Interactively it asks for the name before the OAuth prompts. **Errors immediately if `app-config.json` already exists in the working directory** — move elsewhere or use `brevo app scaffold` there instead. Otherwise resolves (creates/`cd`s into) a target directory, creates the app, and writes the basic project structure (`app-config.json` + `.gitignore`/`AGENTS.md`/`CLAUDE.md`/`README.md`). It scaffolds a feature (OAuth test server) only when the interactive confirm (*"Scaffold the Test OAuth App?"*, default yes) is answered yes; non-interactive runs (`--json` or piped) stay base-only — add the feature afterward with `brevo app scaffold`. |
+| `brevo app upload` | Push `app-config.json` to Brevo (`--yes`, `--json`). No edit flags — change name/redirect URLs/scopes/logo/version by editing `app-config.json` directly, then run `upload`. **`distribution_type` is immutable** — set at `app create` time; if the local value differs from the server, `upload` errors before pushing (restore the local value, or create a new app). Always fetches the remote app first and shows a local-vs-server diff (even under `--yes`/`--json`); exits 0 with no network push if nothing differs. |
+| `brevo app credentials` | Show client ID / secret (`--app-id`, `--reveal-secret`, `--json`). **`--app-id` is required when scripting** — see the picker note below. Also backfills a missing top-level `version` / `distribution_type` into cwd's `app-config.json` when its `appId` matches (fill-only-when-missing, silent). |
+| `brevo app delete` | Delete an app (`--app-id`, `--force`, `--json`). **`--app-id` is required when scripting** — see the picker note below. |
+| `brevo app scaffold` | Add a feature to the app in the current directory (`--app-id`, `--overwrite`, `--json`). Requires an `app-config.json` in cwd **unless `--app-id <id>` is passed or you accept its bootstrap offer**; reads the linked app from it. `--app-id` in a directory with no config fetches that app and writes `app-config.json` + the base files first — the only way to get a config for an app that already exists, and the migration path off the removed `brevo app update --app-id`. Interactively, omitting `--app-id` in a config-less directory prints *"No app-config.json in this directory…"*, asks **"Set up a project for an app you already have?"** (default yes) and on yes shows an app picker; answering no exits `0` with the remaining routes on screen. Every interactive bootstrap (picker or `--app-id`) then asks `Output directory:` defaulted to `./<slugified app name>`, creates it and `cd`s into it — answer `.` to stay in the current directory — and the *Next steps* box opens with `cd <dir>`. Under `--json` or off a TTY there is no offer — it errors, listing the three ways out. It refuses, before any network call: if the directory is already linked to a different app — either the one the command ran in or the one it was pointed at (naming the app it is already linked to is a no-op), if the directory is **inside** an existing app project (a nested second config would make a later `brevo app upload` from there push the wrong app). Diffs the local config against the server and, on drift, updates `app-config.json` to match (on consent) before writing the feature files — including when a bootstrap is pointed at a directory that already holds a project, where answering **Merge** to the directory question does *not* skip that refresh. When feature files already exist, prompts Overwrite / Merge / Cancel (default Merge — existing files kept); `--overwrite` forces overwrite and skips the prompt. The scaffolded OAuth flow is the confidential-client flow: the token exchange is authenticated with the `CLIENT_SECRET` written into the generated `.env.local`. |
 | `brevo app start oauth` | Run the scaffolded OAuth test server (`--port`) |
 | `brevo app available-scopes` | List OAuth scopes supported by the IdP (`--json`, `--web`) |
 | `brevo skill:cli install` | Install the brevo-cli Claude Code skill (Claude-only; auto-refreshes on every `brevo` run) |
@@ -78,30 +90,61 @@ Run `brevo --help` or `brevo <command> --help` for the full set.
 
 ## Conventions
 
-- **Every command supports `--json`** — prefer this when parsing output programmatically.
-- **`app-config.json`** in the working directory pins the linked app — `brevo app update` and `brevo app start` read from it. The optional top-level `logoUri` string is pushed as `logo_uri` by a flagless `brevo app update`; leave it empty to keep the API value untouched.
+- **Every command supports `--json`** — prefer this when parsing output programmatically. It applies to failures too: a failing `--json` run writes a single `{"error": {...}}` document to stdout (see *JSON errors* below) while the human message goes to stderr.
+- **`app-config.json` describes an OAuth app.** It carries `auth.scopes` / `auth.redirectUris` alongside the top-level `appId` / `appName` / `logoUri` / `version` / `distribution_type`. Write only the keys documented here — `brevo app upload` validates the whole file and rejects anything it doesn't recognise.
+- **`brevo app create` refuses to run inside an already-linked directory.** If `app-config.json` exists in cwd, it throws immediately (no confirm, no override) — the error points at moving elsewhere or running `brevo app scaffold` there.
+- **`brevo app create` resolves its target directory before creating the app**, then writes the **basic project structure only** (`app-config.json` + `.gitignore`/`AGENTS.md`/`CLAUDE.md`/`README.md`) — the OAuth server code is a *feature*, not part of the base. Interactive mode prompts for the target directory (default `./<slugified-app-name>`, `cd`s into it) before the API call, how to handle an existing one (overwrite / merge / choose a different path), and — after the app is created — whether to scaffold a feature (*"Scaffold the Test OAuth App?"*, default **yes**). There is no follow-up "which feature?" question while the CLI ships one: a list of one is not asked, and the confirm names it instead. A second feature would bring the picker back. Non-interactive runs stay base-only: `--json` (and piped, non-TTY) create the app and write the base files but never scaffold a feature — run `brevo app scaffold` afterward for the OAuth code. Under `--json` the same default directory is used and `cd`d into if it doesn't already exist; if it already exists, both directory setup and scaffolding are skipped (the app is still created). The JSON response always includes `directory` (absolute path) alongside the app fields, plus either `scaffolded` (base file count, on success) or `scaffoldSkipped` (a message, when the directory already existed).
+- **`brevo app scaffold` adds a feature to an already-created project, or sets an empty directory up for an app that already exists.** It **requires** an `app-config.json` in cwd unless `--app-id` is passed or its bootstrap offer is accepted, and only the bootstrap mode ever creates a directory (the feature-add mode always writes into the project it was run in). **`--app-id <id>` bootstraps a project for an app that already exists**: it fetches the app, writes `app-config.json` + the base files, and then continues into the feature flow. That is the only command that produces a config for an existing app (`app create` creates a new one, `app upload` only reads the linked project), which makes it the migration path off the removed `brevo app update --app-id`. **Interactively, `--app-id` is optional**: in a config-less directory the command explains there is no app here, asks *"Set up a project for an app you already have?"* (default **yes**), and on yes runs the same app picker `app delete` uses — because a user who has lost their project folder has the app but not necessarily its ID. Declining is a normal outcome that exits `0` after printing the remaining routes; the offer is skipped entirely under `--json` or off a TTY, where the no-config error (naming all three ways out: `cd` into a project, `--app-id`, `brevo app create`) is raised instead, so scripts behave exactly as before. **An interactive bootstrap also asks where to put the project** — `Output directory:`, defaulted to `./<slugified app name>`, the same prompt (and the same overwrite / merge / choose-a-different-path follow-up on an existing directory) `app create` uses; it creates the directory, `cd`s the CLI process into it, writes and reports the project, then asks *"Scaffold the Test OAuth App?"* (default yes; declining leaves the project and exits `0`), and opens *Next steps* with `cd <dir>` since the user's shell stayed behind. Answering `.` keeps the current directory and drops that step. This too is interactive-only: under `--json` or off a TTY the files go into the current directory as they always have, which is what makes `scaffold --app-id` safe to script. In bootstrap mode the config is written from the server's copy of the app, since there is nothing local to read it from. Bootstrapping is refused, before any network call or write, in two cases: a directory already linked to a **different** app (passing the app it is already linked to changes nothing), and a directory **inside** an existing app project — `readProjectConfig` reads cwd only and never walks up, so without that check a stray `cd` would nest a second `app-config.json` inside the first and a later `app upload` from there would push the wrong app silently. The different-app check applies to the answer to `Output directory:` as well as to cwd, and there it is the only thing standing between you and a project whose `app-config.json` and `src/oauth/.env.local` name two different apps. **A target directory that already holds a project for the same app makes the bootstrap a refresh**: its config is diffed against the server and rewritten only on consent, and the directory question's **Merge** answer does not suppress that. The two answers address different things — Merge means "don't clobber my own files" and is implemented by skipping any path that already exists, which `app-config.json` always does here, so letting it govern the base write meant the command fetched the app, discarded every field, wrote nothing, and still printed its success box. No drift leaves `app-config.json` as it is with a one-line notice; the feature is still offered either way. It otherwise reads the linked app id from that config (no picker — the picker is only for the config-less bootstrap), diffs the local config against the server, and if fields drifted it shows them and asks consent to update `app-config.json` (and the other base files) to match before writing the feature files. When any feature file already exists it prompts **Overwrite / Merge / Cancel** (default **Merge** — existing, e.g. hand-edited, files are kept and only missing files added; Cancel aborts without writing). The `--overwrite` flag forces a full overwrite of feature files and skips that prompt (works interactively and under `--json`). **Under `--json` it never prompts**: a config diff comes back as `{ "cancelled": true, "reason": "...", "diffs": [...] }`; otherwise it writes the feature (merging existing files unless `--overwrite` is passed) and returns `{ "scaffolded": <n>, "directory": "..." }`.
+- **`app-config.json`** in the working directory pins the linked app — `brevo app upload` and `brevo app start` read from it. `upload` is the *only* command that pushes config changes, and it has no `--app-id` override (it always resolves the app from cwd's `app-config.json`, hard-erroring if that file is missing/invalid/lacks `appId`); `brevo app start` accepts `--app-id` to target a different app. The top-level `logoUri` string is pushed as `logo_uri`; leave it empty to keep the API value untouched. The top-level `version` string is round-tripped as `version` on the wire — `upload` sends the local value (falling back to the server's current value if locally absent) and writes back whatever the server confirms. `brevo app credentials` additionally backfills a missing top-level `version` / `distribution_type` into cwd's `app-config.json` when its `appId` matches the inspected app — fill-only-when-missing (never overwrites an existing local value), silent in all modes — so legacy projects that are never `upload`ed still converge to the current shape.
+- **Commands that pick an app interactively refuse to do so when scripted.** `brevo app credentials` and `brevo app delete` fall back to an interactive app picker when `--app-id` is absent. Under `--json` **or** off a TTY that picker is refused up front — before any network call — with a `CliError` naming the exact command to run (`brevo app credentials --app-id <id>`) and exiting `1`. **Always pass `--app-id` when scripting these.** The refusal exists because the picker renders its choice list to stdout, which would otherwise corrupt the single-JSON-document contract below and leak app ids into whatever is parsing it. `brevo app delete` is the one that matters most: it is destructive, so a script that relied on the picker was never doing what its author thought.
+- **There is no `brevo app update`.** It was removed and replaced by `brevo app upload`, with no shim and no flag-for-flag equivalent — change an app's name, redirect URLs, scopes or logo by editing `app-config.json`, then run `brevo app upload`. That is what to replace it with wherever you find it: a user's script, a CI job, a README, or your own recollection. Invoking it — with any of the old flags (`--name`, `--redirect-uri`, `--scope`, `--logo-uri`, `--app-id`), with `--help`, or as `brevo app help update` — prints a message naming `upload` and exits `1` **without uploading anything**, so a `1` from `brevo app update` means the command is gone, not that an upload failed. It is absent from every help screen, and needs no login to reach.
 - **Credentials** live at `~/.brevo/credentials.json`. Never commit this file or any `.env.local`.
 - **Non-interactive auth:** `BREVO_API_KEY=xkeysib-... brevo login`. The legacy `--api-key` flag was removed because it leaks into shell history.
-- **Skip prompts:** `--force` for delete/logout; `--yes` for `app update`.
+- **Skip prompts:** `--force` for `app delete` and `logout`; `--yes` for `app upload`.
 - **Forced update:** when the installed CLI is a full **major** version behind the latest npm release, every command except `--help`/`--version` prints a blocking update banner to stderr and exits `1` without running. Update with `npm install -g @getbrevo/cli` (or `yarn global add`). The gate honors the same opt-outs as the soft update notice (`BREVO_NO_UPDATE_NOTIFIER=1`, `--no-update-notifier`, CI, non-TTY), so it never fires in those contexts.
+- **Update notice wording:** the update/force-update banners take their first line from the app-store service (`GET /cli/info`). It is called directly, not through the v3 API gateway, and needs no API key — so it works while logged out or with expired credentials. It runs once per invocation, **before** the command, and the response is cached at `~/.brevo/cli-info-cache.json` for **15 minutes**, keyed to the installed `cliVersion` — so reworded text or a new block reaches the CLI within minutes rather than after the old 12h npm-style TTL. Whether an update banner appears is still decided from the npm registry, and if the call fails the banner still appears with local wording (a failed call never overwrites a good cache entry).
+- **Soft update notice on failures:** the non-blocking update banner also prints after a command *fails*, not just after it succeeds — so stderr may hold the error message followed by the update box. Exit codes are unchanged (still the command's own), the box never appears twice in one run, and a Ctrl-C abort skips it. Parse stderr accordingly, or set `BREVO_NO_UPDATE_NOTIFIER=1` / pass `--no-update-notifier`.
+- **Server-side block:** `GET /cli/info` may answer `"is_blocked": true`, in which case every command except `--help` / `--version` prints a banner to stderr and exits `1` **without running** — independently of the npm major-version gate. Unlike the update notice, this is **not** suppressed by `BREVO_NO_UPDATE_NOTIFIER=1`, `--no-update-notifier`, CI, or a non-TTY: a hidden banner must never mean a hidden block. It fails open — a timeout, a non-2xx, or an unparseable body lets the command run, and only a literal `true` blocks. So a `brevo` call that suddenly exits `1` with an update banner may mean either a major-version gap or a server-side block; both are cleared by upgrading. Because the verdict is cached for 15 minutes, a lifted block can take up to 15 minutes to clear on a machine that already cached the blocked answer — delete `~/.brevo/cli-info-cache.json` for an immediate re-check. Note `--help` / `--version` are exempt from the block only, not from the lookup: they still fetch `/cli/info` and still show the server's wording on their update banner, they just never exit non-zero because of it.
 - **Exit codes:** `0` success · `1` general error · `2` aborted · `3` auth · `4` network · `5` not found.
 
+## JSON errors
+
+Under `--json`, a failing command writes **one** JSON document to stdout describing the failure; the human-readable message still goes to stderr. The `error` key is the discriminator — no success payload has one:
+
+```json
+{ "error": { "name": "CliError", "message": "Not authenticated. Run: brevo login", "exitCode": 1 } }
+```
+
+| Field | Always present | Meaning |
+| --- | --- | --- |
+| `name` | yes | Error class — `CliError`, `ApiError`, `AuthExpiredError`, `AbortError` |
+| `message` | yes | Same text written to stderr |
+| `exitCode` | yes | Matches the process exit code |
+| `statusCode` | `ApiError` only | HTTP status behind the failure |
+| `code` | `ApiError`, when classified | `AUTH_INVALID`, `AUTH_EXPIRED`, `ACCESS_DENIED`, `APP_NOT_FOUND`, `REDIRECT_INVALID`, `PORT_IN_USE`, `NETWORK_ERROR`, `RATE_LIMITED`, `APP_LIMIT_REACHED`, `REGISTRY_ERROR`, `AUTH_GATEWAY` |
+
+Stdout is always **exactly one** parseable document. Commands that already describe their own failure keep their shape rather than emitting this envelope — `brevo whoami --json` returns `{"authenticated": false, "reason": "no_key"}` (exit `1`). Check for `error` first, then fall back to the command's own shape.
+
+## Command help
+
+`brevo --help` prints the grouped overview of every command. `brevo <command> --help` prints that command's own usage line, arguments, flags, and examples — e.g. `brevo app scaffold --help` documents `--app-id` / `--overwrite` / `--json`. Use it to confirm a flag exists on the installed version rather than assuming from this file.
+
 ## Scopes
 
 - New apps created via `brevo app create` default to `contacts:read`, `contacts:write`, `crm:read`, `crm:write`. The CLI prints these on success.
-- `brevo app update --scope <scope>` is repeatable and appends, mirroring `--redirect-uri`. De-duped, order-preserving. Writes back to `app-config.json` when that file describes the target app. A single flag value may contain multiple comma- or whitespace-separated tokens (`--scope "crm:read, crm:write"` is equivalent to `--scope crm:read --scope crm:write`). Same normalization is applied to `auth.scopes` when read from `app-config.json`.
+- To change scopes, redirect URLs, name, logo, or version, edit the corresponding field in `app-config.json` directly and run `brevo app upload` — there is no `--scope`/`--redirect-uri`/`--name`/`--logo-uri` flag on `upload`. Same normalization (comma/whitespace-split, de-duped) is applied to `auth.scopes` when read from `app-config.json`. `distribution_type` cannot be changed this way — it is immutable after `app create`, and `upload` errors if the local value drifts from the server.
 - `brevo app available-scopes [--json] [--web]` lists the OAuth scopes the IdP currently supports. It reads a **public** catalog and works **without `brevo login`** (no API key needed). Text output groups names by category (e.g. `account`, `data_crm`, `messaging`); `--json` returns a flat `{ scopes: string[] }` of names. OIDC-reserved scopes (`openid`, `profile`, `email`, `offline_access`) and magic wildcards are excluded. The CLI validates scope **format** locally (must match `[A-Za-z0-9][A-Za-z0-9:_.-]*`) but does **not** validate that a scope is recognized by the IdP — server returns 400 on unknown scopes.
 - Passing `--web` to `brevo app available-scopes` additionally starts a short-lived loopback HTTP server on `127.0.0.1:<ephemeral>` rendering the same catalog as a styled HTML page and opens the user's browser. It stays in the foreground until Ctrl+C. Without `--web` the command exits after printing the list — TTY detection no longer triggers the browser. `--json` always suppresses the browser (`--json` returns before `--web` is evaluated).
 
 ### Legacy `'all'` scope deprecation
 
-The legacy catch-all `'all'` OAuth scope is deprecated. The CLI **blocks** `brevo app update` and `brevo app start oauth` when scopes still contain `'all'` (no escape hatch, no silent rewrite); the only mutating path that proceeds is an explicit `--scope` migration. To handle a legacy app:
+The legacy catch-all `'all'` OAuth scope is deprecated. The CLI **blocks** `brevo app upload` and `brevo app start oauth` when scopes still contain `'all'` (no escape hatch, no silent rewrite); the only mutating path that proceeds is editing `auth.scopes` in `app-config.json` and running `upload`. To handle a legacy app:
 
 1. **Detect** `'all'` in `auth.scopes` of a local `app-config.json`, or on a remote app via `brevo app list --json` — affected apps carry `"legacy_all_scope": true` (text output appends `(legacy 'all' — deprecated)` to the scopes line).
 2. **Prompt the user to pick granular scopes** — use `brevo app available-scopes --json` for the catalog, or fall back to the four defaults (`contacts:read`, `contacts:write`, `crm:read`, `crm:write`).
-3. **Migrate** with `brevo app update --scope <scope> --scope <scope> ...` — passing `--scope` drops `'all'` from the outgoing scope set and applies the new granular scopes (the summary shows a "Migrating from legacy 'all' scope" line and `all (removed)`).
+3. **Migrate** by editing `auth.scopes` in `app-config.json` to replace `'all'` with the granular scopes your integration uses, then run `brevo app upload` (the summary shows a "Migrating from legacy 'all' scope" line and `all (removed)`).
 
-`brevo app scaffold` against an app whose remote scopes contain `'all'` never propagates it: the new `app-config.json` keeps the app's remaining granular scopes (or the four default scopes when `'all'` was the only scope), with a one-line substitution notice (suppressed under `--json`). Note the substitution is local-only — the remote app still needs the `--scope` migration above.
+Writing `app-config.json` for an app whose remote scopes contain `'all'` never propagates it: the file keeps the app's remaining granular scopes (or the four default scopes when `'all'` was the only scope), with a one-line substitution notice (suppressed under `--json`). This happens when `brevo app create` writes the base config and when `brevo app scaffold` rewrites it after a detected server drift. Note the substitution is local-only — the remote app still needs the `app-config.json` edit + `brevo app upload` migration above.
 
 ## Environment variables
 
@@ -110,10 +153,11 @@ The legacy catch-all `'all'` OAuth scope is deprecated. The CLI **blocks** `brev
 | `BREVO_API_KEY` | Non-interactive login |
 | `BREVO_API_URL` | Override API base (HTTPS required, except `localhost`) |
 | `BREVO_OAUTH_PROXY_URL` | Override OAuth proxy used by browser login |
+| `BREVO_APP_STORE_URL` | Override the app-store service base used for the update notice and the server-side block check (HTTPS required, except `localhost`) |
 | `BREVO_CONFIG_HOME` | Override credentials directory (default `~/.brevo/`) |
 | `BREVO_CLAUDE_HOME` | Override Claude Code home used by `skill:cli` (default `~/.claude/`) |
 | `BREVO_NO_SKILL_AUTOREFRESH` | Set to `1` to suppress automatic skill refresh on `brevo` runs |
-| `BREVO_NO_UPDATE_NOTIFIER` | Set to `1` to suppress the npm update-available notice **and** the blocking major-version force-update gate |
+| `BREVO_NO_UPDATE_NOTIFIER` | Set to `1` to suppress the npm update-available notice **and** the blocking major-version force-update gate. Does **not** suppress a server-side `is_blocked` block. |
 | `BREVO_DEBUG=1` or `--debug` | Verbose HTTP and error logging |
 
 ## Safety

package/agent-context/SKILL.md

@@ -7,6 +7,18 @@ description: Use when working in a project that uses the Brevo Developer CLI (th
 
 This project uses the Brevo Developer CLI to create and manage Brevo OAuth applications. Treat the `brevo` binary as the canonical entry point — don't shell out to `curl https://api.brevo.com/...` for things the CLI already covers.
 
+## `brevo --help` is the source of truth
+
+Brevo features that haven't been released are **not built into the published CLI at all** — not as hidden commands, not behind a flag or an env var. `brevo --help` and `brevo app --help` list everything the binary can do. Treat that as the complete surface and build from it.
+
+What this means in practice:
+
+- **If a command isn't in `--help`, it doesn't exist here.** Invoking it gives Commander's `unknown command` and exit `1`. That is a final answer, not a transient failure and not a permissions problem — there is no flag, config edit, account setting, or environment variable that reveals it. Don't retry, don't hunt for an alternative route, and don't tell the user to get access. Say the feature isn't available in this CLI and offer the nearest thing that works.
+- **Don't act on a command you remember rather than one you can see.** Your recollection of the Brevo CLI may include commands from a newer or unreleased build. `--help` in the current session is the only reliable source.
+- **A flag can be rejected even when its command exists.** `--distribution` is a real flag, but a value tied to an unreleased feature is refused with *"That command is not available yet. It is part of a Brevo feature that has not been released."* Same rule: it's final. Use `--distribution private`.
+
+The Brevo API enforces the same boundaries independently, so nothing is gained by trying to route around the CLI — a hand-rolled `curl` hits the platform's own refusal.
+
 > **Reading this from the repo rather than `~/.claude/skills/brevo-cli/`?**
 >
 > - **If you're Claude Code** (CLI or desktop app — any agent that reads `~/.claude/skills/`): install it as a skill with `brevo skill:cli install` so your tooling loads it natively and keeps it auto-refreshed. The repo copy is bundled with the npm package; the installed copy is what Claude actually consumes. Note: the Claude Desktop **chat** app does not read `~/.claude/skills/`, so the installed skill won't load there — only Claude Code surfaces pick it up.
@@ -40,54 +52,98 @@ Don't fall back to raw HTTP against `api.brevo.com` — the `brevo` binary is th
 - "Authenticate" → `brevo login` (or `BREVO_API_KEY=xkeysib-... brevo login` for CI)
 - "Who am I logged in as?" → `brevo whoami --json`
 - "Show / pick an app" → `brevo app list --json`
-- "Create an app" → `brevo app create --name "<name>" --distribution private --redirect-uri <url> --json` (add `--logo-uri <https://…>` to set the app logo at creation time; new apps default to scopes `contacts:read`, `contacts:write`, `crm:read`, `crm:write`). Only `private` distribution is available today — the CLI rejects `--distribution public` with a "coming soon" error, so never suggest it.
-- "Update app metadata" → `brevo app update --app-id <id> --name "<name>"` and/or `--redirect-uri <url>` (repeatable) and/or `--scope <scope>` (repeatable, appends) and/or `--logo-uri <https://…>`
-- "Get client credentials" → `brevo app credentials --app-id <id> --json` (add `--reveal-secret` to print the secret)
-- "Generate starter OAuth code" → `brevo app scaffold --app-id <id>`
+- "Create an app" → `brevo app create --name "<name>" --distribution private --redirect-uri <url> --json` (add `--logo-uri <https://…>` to set the app logo at creation time; new apps default to scopes `contacts:read`, `contacts:write`, `crm:read`, `crm:write`). **Use `--distribution private`** — check `brevo app create --help` for the values your account accepts, and don't pass one it doesn't list. **Fails immediately if run from a directory that already has `app-config.json`** — `cd` elsewhere first, or use `brevo app scaffold` in that directory instead. Otherwise resolves (creates/`cd`s into) its target directory, creates the app, and writes the **basic project structure** (`app-config.json` + `.gitignore`/`AGENTS.md`/`CLAUDE.md`/`README.md`). It scaffolds a feature (the OAuth test server) **only** when the interactive confirm (*"Scaffold the Test OAuth App?"*, default yes) is answered yes — there is no separate "which feature?" question while the CLI ships one; **non-interactive runs (`--json` or piped) stay base-only** — run `brevo app scaffold` afterward to add the OAuth code. Under `--json`, the response's `directory` field is where it landed and `scaffolded` is the base file count; check for `scaffoldSkipped` instead of `scaffolded` if that directory already existed (both directory setup and scaffolding are skipped together in that case, but the app is still created).
+- "Update app metadata" → edit the relevant field(s) in `app-config.json` (`appName`, `auth.redirectUris`, `auth.scopes`, `logoUri`, `version`) (older projects may still say `auth.redirectUrls` — the CLI reads it and migrates the file to `redirectUris` on its next write), then run `brevo app upload --json` (no `--app-id`/`--name`/`--redirect-uri`/`--scope`/`--logo-uri` flags exist — `upload` always pushes the whole file, resolved only from cwd's `app-config.json`). **`distribution_type` is immutable** — it's set at `app create` time and cannot be changed via `upload`; if the local value differs from the server, `upload` errors and tells you to restore it (create a new app to get a different distribution). **There is no `brevo app update`** — it was removed, with no shim and no flag-for-flag equivalent; if you find it in a user's script, CI job, README, or your own recollection, replace it with the edit-then-`upload` flow above. Invoking it — with any of the old flags, with `--help`, or as `brevo app help update` — prints a message naming `brevo app upload` and exits `1` **without uploading anything**, so a `1` from `brevo app update` means the command is gone, not that an upload failed.
+- "Get client credentials" → `brevo app credentials --app-id <id> --json` (add `--reveal-secret` to print the secret). **`--app-id` is not optional here** — without it the command wants an interactive app picker, and under `--json`/off a TTY it refuses with exit `1` rather than prompting.
+- "Set up a project for an app that already exists" → `brevo app scaffold --app-id <id>` (`brevo app list` gives the IDs). Fetches the app and writes `app-config.json` + the base files, then adds a feature as below. Interactively it asks which directory to write into first (default `./<slugified app name>`); under `--json`/off a TTY it uses the current one. **This is the only way to get an `app-config.json` for an existing app** — `brevo app create` makes a *new* app, and `brevo app upload` only ever reads the project in the current directory. It refuses if the directory is already linked to a *different* app; pointing it at the app the directory is already linked to is a no-op. **Interactively you can omit `--app-id`**: plain `brevo app scaffold` in a directory with no `app-config.json` says so, asks *"Set up a project for an app you already have?"* (default yes), and on yes lists the account's apps so you can pick one — no need to look the ID up first. **Every interactive bootstrap (picker or `--app-id`) then asks `Output directory:`, defaulted to `./<the app's name slugified>`** — the same question `brevo app create` asks — creates that directory and `cd`s into it, so the files don't land in whatever folder you happened to be standing in; answer `.` to use the current directory instead. It then writes the project (`app-config.json` + the base files), shows what it wrote, and asks *"Scaffold the Test OAuth App?"* (default yes) — declining is normal and leaves the project in place, exit `0`. The *Next steps* box opens with `cd <dir>`, because the CLI can only move its own process, never your shell. **Under `--json` or off a TTY there is no directory question and the files go into the current directory**, so scripted `brevo app scaffold --app-id <id>` runs are unchanged — `mkdir` and `cd` yourself first if you want them somewhere specific. Answering **no** is a normal outcome, not an error: it exits `0` after printing the remaining routes (`brevo app create` here, or `cd` into an existing project). **Always pass `--app-id` when scripting** — the offer needs a terminal, so under `--json` or off a TTY the command errors instead of prompting. **If the directory you point it at already holds a project, the bootstrap is a refresh, not a fresh write**: the config found there is diffed against the server and rewritten only on consent (*"…will update app-config.json to match the server. Continue?"*, default yes) — answering **Merge** at the directory question does not suppress that, because merging keeps the file that exists and so would skip the very file a bootstrap is for. No drift means `app-config.json` is left alone with a one-line notice, and the feature still gets added. A directory holding a project for a **different** app is refused outright, naming both apps. Two refusals apply to both forms, before any write: that different-app case, and the directory must not be **inside** an existing project (a nested second `app-config.json` would make a later `brevo app upload` push the wrong app).
+- "Add a feature (e.g. the OAuth test server) to an existing project" → `brevo app scaffold` (run **inside** the project directory; it reads the linked app from `app-config.json`, so `--app-id` is only needed to bootstrap a directory that has none). Not needed right after `app create` if you already accepted the feature prompt there. If feature files already exist it prompts Overwrite / Merge / Cancel (default Merge); pass `--overwrite` to force a full overwrite without prompting. **The scaffolded OAuth flow is the confidential-client flow:** `/auth/callback` authenticates the token exchange with the `CLIENT_SECRET` written into the scaffolded `.env.local`.
 - "Run the OAuth test server" → `brevo app start oauth --port 3009` (must be inside the scaffolded directory)
-- "Delete an app" → `brevo app delete --app-id <id> --force`
+- "Delete an app" → `brevo app delete --app-id <id> --force`. **`--app-id` is not optional here either** — omitting it means an interactive picker, which under `--json`/off a TTY is refused with exit `1`. Never script a delete without naming the app.
 - "List supported OAuth scopes" → `brevo app available-scopes --json`
 - "Sign out" → `brevo logout --force`
 
 ## Hard rules
 
-1. **Always pass `--json`** when you intend to parse output. Every command supports it.
+1. **Always pass `--json`** when you intend to parse output. Every command supports it, **on success and on failure alike** — a failing `--json` run writes a single `{"error": {...}}` document to stdout (see *JSON errors* below), so you can read the reason instead of only seeing a non-zero exit.
 2. **Never print, log, or commit** API keys (`xkeysib-…`), client secrets, refresh tokens, or contents of `~/.brevo/credentials.json` / `.env.local`. Redact before sharing diagnostics.
 3. **Don't use `--api-key`** — the flag was removed. Use the `BREVO_API_KEY` env var.
-4. **Don't run `brevo app scaffold` inside an existing scaffolded project** — it refuses if `app-config.json` exists in cwd. Use `brevo app update` to push config changes.
+4. **`brevo app create` refuses to run inside an already-linked directory** (`app-config.json` present) — `cd` elsewhere or use `brevo app scaffold` there instead. **`brevo app scaffold` requires an `app-config.json` in the current directory unless you pass `--app-id` or answer its bootstrap offer** (it adds a feature to an already-created project); with none present and no `--app-id` it offers to set the directory up for an existing app when interactive, and otherwise errors, listing the three ways out (`cd` into a project, `--app-id` to set this directory up for an app you already have, or `brevo app create` for a new one). With `--app-id <id>` in a directory that has no config it fetches that app, asks (interactively only) which directory to write into — default `./<slugified app name>`, `.` to stay put — writes `app-config.json` + the base files there, and continues; that is the migration path off the removed `brevo app update --app-id`, and off a TTY or under `--json` it writes into the current directory with no prompt. If the directory it is told to write into already holds a project for the **same** app, it diffs that config against the server and rewrites it only on consent — the directory prompt's **Merge** answer does not silently skip the refresh, and no drift leaves `app-config.json` untouched with a notice. It refuses (before any network call) if the directory is already linked to a *different* app — whether that is the directory the command ran in or the one it was pointed at — or if the directory is **inside** an existing app project (a nested second `app-config.json` would make a later `brevo app upload` from there push the wrong app — `cd` to the project root or outside it). It reads the linked app from that config, diffs the config against the server, and if fields drifted it tells you and (on consent) rewrites `app-config.json` to match before writing the feature files. When any feature file already exists it prompts **Overwrite / Merge / Cancel** (default **Merge** — existing, e.g. hand-edited, files are kept; Cancel aborts). Pass `--overwrite` to force a full overwrite and skip that prompt (works interactively and under `--json`). **Under `--json` it never prompts**: a config diff comes back as `{ "cancelled": true, "reason": "...", "diffs": [...] }`; otherwise it scaffolds the feature (merging existing files unless `--overwrite` is passed) and returns `{ "scaffolded": <n>, "directory": "..." }`.
 5. **Prefer flag-driven over interactive** in agent contexts: `--name`, `--app-id`, `--force`, `--yes` so the command doesn't block on prompts.
+6. **Write only the `app-config.json` keys this file documents.** `brevo app upload` validates the whole file and rejects keys it doesn't recognise, so an invented block fails at upload rather than doing anything useful.
 
 ## Locating the linked app
 
-If `app-config.json` exists in the working directory, it pins the app — `brevo app update` and `brevo app start` use it automatically. To target a different app, pass `--app-id`.
+If `app-config.json` exists in the working directory, it pins the app — `brevo app upload` and `brevo app start` use it automatically. `brevo app start` accepts an `--app-id` override to target a different app; `upload` does **not** — it only ever reads cwd's `app-config.json`, hard-erroring if that file is missing, invalid, or lacks `appId`.
+
+`app-config.json` carries an optional top-level `logoUri` string. When set, `brevo app upload` pushes it as `logo_uri`; when empty / absent, the field is left untouched on the API.
+
+`app-config.json` also carries a top-level `version` string, shown by `brevo app create`/`brevo app list`. `brevo app upload` sends it on the wire as `version` (falling back to the server's current value if locally absent) and writes back whatever version the server confirms after a successful upload.
 
-`app-config.json` carries an optional top-level `logoUri` string. When set, a flagless `brevo app update` pushes it as `logo_uri` in the PUT body; when empty / absent, the field is left untouched on the API.
+`brevo app credentials` also backfills a legacy `app-config.json` toward the current shape: when the file exists in cwd and its `appId` matches the app being inspected, any missing top-level `version` / `distribution_type` is filled in from the server (fill-only-when-missing — an existing local value is never overwritten). This runs silently in all modes; human output prints a one-line note when something was written. It's how projects that are never `upload`ed still converge.
 
 ## Scopes
 
-- New apps created via `brevo app create` default to `contacts:read`, `contacts:write`, `crm:read`, `crm:write`. The CLI prints the default set on success and points to `brevo app update --scope` for changes.
-- `brevo app update --scope <scope>` is **repeatable and appends** — passing `--scope X --scope Y` adds both to the app's existing scope set, de-duped, order-preserving. A single flag value may also contain multiple comma- or whitespace-separated tokens (`--scope "crm:read, crm:write"` ≡ `--scope crm:read --scope crm:write`); the same normalization is applied to `auth.scopes` when read from `app-config.json`, so a malformed entry like `"crm:write, campaigns:read"` is split into two scopes on read. To see what's currently set, run `brevo app credentials --app-id <id> --json`. To remove a scope, edit `app-config.json` and run `brevo app update` without `--scope`.
+- New apps created via `brevo app create` default to `contacts:read`, `contacts:write`, `crm:read`, `crm:write`. The CLI prints the default set on success and points to editing `app-config.json` + `brevo app upload` for changes.
+- To add, remove, or change scopes: edit `auth.scopes` in `app-config.json` directly, then run `brevo app upload`. Comma- or whitespace-separated values are normalized on read, whether they sit in a single array entry (`["crm:read", "crm:write, campaigns:read"]`) or replace the array entirely (`"crm:write, campaigns:read"`) — either becomes two scopes. To see what's currently set, run `brevo app credentials --app-id <id> --json`.
 - `brevo app available-scopes [--json] [--web]` lists the OAuth scopes the IdP currently supports. It reads a **public** catalog and works **without `brevo login`** (no API key needed). Text output groups names by category (e.g. `account`, `data_crm`, `messaging`); `--json` returns a flat `{ scopes: string[] }` of names. OIDC-reserved scopes (`openid`, `profile`, `email`, `offline_access`) and magic wildcards are excluded. The CLI validates scope **format** locally (must match `[A-Za-z0-9][A-Za-z0-9:_.-]*`) but does **not** validate that a scope is recognized by the IdP — use `app available-scopes` to confirm spelling before passing an unfamiliar scope.
 - Passing `--web` to `brevo app available-scopes` **also opens a browser** to a styled local page (loopback `http://127.0.0.1:<port>/`) and stays running until Ctrl+C. Without `--web` the command exits after printing the list — TTY detection no longer triggers the browser. `--json` always suppresses the browser, so agent invocations using `--json` behave the same regardless of `--web`.
 
 ### Legacy `'all'` scope deprecation
 
-The legacy catch-all `'all'` OAuth scope is deprecated. The CLI **blocks** `brevo app update` and `brevo app start oauth` when scopes still contain `'all'` (no escape hatch, no silent rewrite); the only mutating path that proceeds is an explicit `--scope` migration. To handle a legacy app:
+The legacy catch-all `'all'` OAuth scope is deprecated. The CLI **blocks** `brevo app upload` and `brevo app start oauth` when scopes still contain `'all'` (no escape hatch, no silent rewrite); the only mutating path that proceeds is editing `auth.scopes` in `app-config.json` and running `upload`. To handle a legacy app:
 
 1. **Detect** `'all'` in `auth.scopes` of a local `app-config.json`, or on a remote app via `brevo app list --json` — affected apps carry `"legacy_all_scope": true` (text output appends `(legacy 'all' — deprecated)` to the scopes line).
 2. **Prompt the user to pick granular scopes** — use `brevo app available-scopes --json` for the catalog, or fall back to the four defaults (`contacts:read`, `contacts:write`, `crm:read`, `crm:write`).
-3. **Migrate** with `brevo app update --scope <scope> --scope <scope> ...` — passing `--scope` drops `'all'` from the outgoing scope set and applies the new granular scopes (the summary shows a "Migrating from legacy 'all' scope" line and `all (removed)`).
+3. **Migrate** by editing `auth.scopes` in `app-config.json` to replace `'all'` with the granular scopes your integration uses, then run `brevo app upload` (the summary shows a "Migrating from legacy 'all' scope" line and `all (removed)`).
 
-`brevo app scaffold` against an app whose remote scopes contain `'all'` never propagates it: the new `app-config.json` keeps the app's remaining granular scopes (or the four default scopes when `'all'` was the only scope), with a one-line substitution notice (suppressed under `--json`). Note the substitution is local-only — the remote app still needs the `--scope` migration above.
+Writing `app-config.json` for an app whose remote scopes contain `'all'` never propagates it: the file keeps the app's remaining granular scopes (or the four default scopes when `'all'` was the only scope), with a one-line substitution notice (suppressed under `--json`). This applies when `brevo app create` writes the base config, and when `brevo app scaffold` rewrites it after a detected server drift. Note the substitution is local-only — the remote app still needs the `app-config.json` edit + `brevo app upload` migration above.
 
 ## Exit codes
 
 `0` success · `1` general error · `2` aborted · `3` auth failure · `4` network · `5` not found.
 
+## JSON errors
+
+Under `--json`, a command that fails writes **one** JSON document to stdout describing the failure, and the human-readable message still goes to stderr. The `error` key is the discriminator — no success payload has one:
+
+```json
+{ "error": { "name": "CliError", "message": "Not authenticated. Run: brevo login", "exitCode": 1 } }
+```
+
+`name` is the error class (`CliError`, `ApiError`, `AuthExpiredError`, `AbortError`), `message` is the same text printed to stderr, and `exitCode` matches the process exit code. An `ApiError` adds `statusCode` (the HTTP status) and, when the API classified the failure, `code` — one of `AUTH_INVALID`, `AUTH_EXPIRED`, `ACCESS_DENIED`, `APP_NOT_FOUND`, `REDIRECT_INVALID`, `PORT_IN_USE`, `NETWORK_ERROR`, `RATE_LIMITED`, `APP_LIMIT_REACHED`, `REGISTRY_ERROR`, `AUTH_GATEWAY`:
+
+```json
+{ "error": { "name": "ApiError", "message": "App not found", "exitCode": 5, "code": "APP_NOT_FOUND", "statusCode": 404 } }
+```
+
+Two things to rely on: stdout is always **exactly one** parseable document, and commands that describe their own failure keep doing so instead of emitting this envelope — `brevo whoami --json` still returns `{"authenticated": false, "reason": "no_key"}` (exit `1`). Check for `error` first, then fall back to the command's own shape.
+
+## Command help
+
+`brevo --help` prints the grouped overview of every command. `brevo <command> --help` prints that command's own usage line, arguments, flags, and examples — e.g. `brevo app scaffold --help` documents `--app-id` / `--overwrite` / `--json`. When you need to confirm a flag exists on the version actually installed, read it from there rather than assuming from this file.
+
 ## Forced update
 
 When the installed CLI is a full **major** version behind the latest npm release, every command except `--help` / `--version` prints a blocking update banner to stderr and exits `1` **without running** — so a `brevo` call that suddenly exits `1` with an update banner means the CLI must be upgraded (`npm install -g @getbrevo/cli` or `yarn global add @getbrevo/cli`) before it will work. The gate honors the same opt-outs as the soft update notice (`BREVO_NO_UPDATE_NOTIFIER=1`, `--no-update-notifier`, CI, non-TTY), so it never fires in those contexts.
 
+## Update notice wording
+
+The update banner's first line comes from the app-store service (`GET /cli/info`). It is called directly rather than through the v3 API gateway and requires no API key, so it works while logged out or with expired credentials. It runs once per invocation, **before** the command, and the response is cached at `~/.brevo/cli-info-cache.json` for **15 minutes**, keyed to the installed `cliVersion` — so reworded text or a new block reaches the CLI within minutes rather than after the old 12h npm-style TTL, without a network call on every single command. Whether an update banner appears is still decided from the npm registry, exactly as before, and a failed call just means the banner uses local wording (a failed call never overwrites a good cache entry). `BREVO_APP_STORE_URL` overrides that service's base URL for non-production testing.
+
+## Server-side block
+
+The same response may carry `"is_blocked": true`. When it does, every command except `--help` / `--version` prints a banner to stderr and exits `1` **without running** — a separate mechanism from the major-version gate above, and one the server can turn on without shipping a new CLI.
+
+Those two are exempt from the **block**, not from the lookup: they still call `/cli/info` and still render the server's wording on their update banner. They simply never exit non-zero because of it, so a blocked CLI can always still report what version it is.
+
+Two things to know when you hit this:
+
+- **The notice opt-outs do not apply.** `BREVO_NO_UPDATE_NOTIFIER=1`, `--no-update-notifier`, CI, and a non-TTY all suppress the *notice*; none of them suppress a block. Don't suggest them as a workaround — the only fix is upgrading the CLI.
+- **It fails open.** A timeout, a non-2xx, or an unparseable body lets the command run normally; only a literal `true` blocks. So a network problem never manifests as a block.
+- **A block can persist up to 15 minutes after the server lifts it, and vice versa**, because the whole response is cached. If you need a verdict that reflects the server's *current* state, delete `~/.brevo/cli-info-cache.json` (or bump the version) before checking.
+
+The soft (non-blocking) notice also prints after a command **fails**, not just after it succeeds — so stderr can hold the error message followed by the update box. This does not change exit codes: a failing command still exits with its own code, and the box is never printed twice in one run. A Ctrl-C abort skips it. If you parse stderr strictly, suppress the notice with `BREVO_NO_UPDATE_NOTIFIER=1` or `--no-update-notifier`.
+
 ## Before sharing or committing output
 
 * [ ] No `xkeysib-…` API keys, client secrets, refresh tokens, or contents of `~/.brevo/credentials.json` / `.env.local` in messages, logs, or diffs.