Getting startedAuthenticationOAuth 2.0

CLI reference

Complete reference for the Brevo CLI — install, authenticate, and manage OAuth apps

The Brevo CLI (@getbrevo/cli) lets you create and manage OAuth apps, scaffold starter code, and run a local test server — all from the terminal.

Installation

$npm install -g @getbrevo/cli

Requirements: Node.js >= 20.15.0 (Homebrew installs Node automatically as a dependency).

Verify:

$brevo --version

Authentication commands

brevo login

Authenticate with your Brevo account via browser.

$brevo login

Opens oauth-cli.brevo.com in your browser. After signing in, credentials are saved to ~/.brevo/credentials.json.

FlagDescription
--browserForce browser login (default)
--jsonOutput result as JSON

Example:

$brevo login

brevo logout

Clear stored credentials.

$brevo logout [--force]
FlagDescription
--forceSkip confirmation prompt (required in non-interactive environments)
--jsonOutput result as JSON

Example:

$brevo logout --force

Logout clears cached app credentials (client ID / client secret). Run brevo app credentials --reveal-secret before logging out if you need to save them.

brevo whoami

Show the currently authenticated user.

$brevo whoami
FlagDescription
--jsonOutput result as JSON

Example:

$brevo whoami
$# Authenticated as you@example.com (Acme Corp)

App commands

brevo app init

Guided setup — authenticate, create an app, and scaffold starter code in one flow.

$brevo app init

No flags. Prompts for: app name, distribution type, redirect URL, output directory.

Example:

$brevo app init

Use this for first-time setup. For scripted or automated flows, use brevo app create with flags.

brevo app create

Create a new OAuth app.

$brevo app create [--name <name>] [--distribution <type>] [--redirect-uri <url>] [--logo-uri <url>]
FlagDescription
--name <name>App name
--distribution <type>Distribution type — private (default)
--redirect-uri <url>Redirect URI — repeatable to add multiple URIs
--logo-uri <url>App logo URL (http:// or https://). Optional. When omitted in an interactive shell, the command prompts for it; leave blank to skip.
--jsonOutput result as JSON

Examples:

$# Interactive
$brevo app create
$
$# Non-interactive
$brevo app create --name "My App" --distribution private --redirect-uri http://localhost:3009/auth/callback
$
$# Multiple redirect URIs
$brevo app create --name "My App" \
>  --redirect-uri http://localhost:3009/auth/callback \
>  --redirect-uri https://staging.myapp.com/auth/callback
$
$# With a logo
$brevo app create --name "My App" --distribution private --logo-uri https://example.com/logo.png

brevo app list

List all OAuth apps in your account.

$brevo app list
FlagDescription
--jsonOutput result as JSON

Example:

$brevo app list --json

brevo app credentials

Show credentials for an app.

$brevo app credentials [--app-id <id>] [--reveal-secret]
FlagDescription
--app-id <id>Target app ID. Omit to select interactively.
--reveal-secretShow the client secret (hidden by default). Prompts for confirmation.
--jsonOutput result as JSON

Examples:

$# Show credentials (secret hidden)
$brevo app credentials --app-id e22eb778-a2a8-488a-a5e8-466b6dad9385
$
$# Reveal client secret
$brevo app credentials --app-id e22eb778-a2a8-488a-a5e8-466b6dad9385 --reveal-secret

brevo app update

Update an app’s name, redirect URLs, scopes, or logo URL.

$brevo app update [--app-id <id>] [--name <name>] [--redirect-uri <url>] [--scope <scope>] [--logo-uri <url>] [--yes]
FlagDescription
--app-id <id>Target app ID. Omit to use app-config.json in the current directory.
--name <name>New app name
--redirect-uri <url>Append a redirect URL. Repeatable.
--scope <scope>Append an OAuth scope. Repeat the flag to add multiple scopes.
--logo-uri <url>Set the app logo URL (http:// or https://). Replaces the existing value.
--yesSkip confirmation prompts
--jsonOutput result as JSON

Behavior:

  • With --name, --redirect-uri, --scope, or --logo-uri flags: merges flag values with existing app configuration
  • Without flags (run from a scaffolded project directory): pushes the full app-config.json to Brevo
  • --redirect-uri and --scope append to existing values — they do not replace them. To remove a scope, edit app-config.json and run brevo app update without flags from the project directory.
  • --logo-uri replaces the existing logo URL.
  • Scope values are format-validated locally (^[A-Za-z0-9][A-Za-z0-9:_.-]*$) but not cross-checked against the IdP catalog. Typos surface as invalid_scope errors at authorization time — run brevo app available-scopes first to confirm the spelling.
  • After a successful update, app-config.json is written back automatically

Examples:

$# Rename from a scaffolded project directory
$brevo app update --name "New Name"
$
$# Add a redirect URL
$brevo app update --name "My App" --redirect-uri https://app.example.com/callback
$
$# Add a single scope
$brevo app update --scope transactional.email:write
$
$# Add multiple scopes — repeat the flag
$brevo app update --scope contacts:read --scope contacts:write
$
$# Set or change the app logo
$brevo app update --logo-uri https://example.com/logo.png
$
$# Target a specific app by ID
$brevo app update --app-id e22eb778-a2a8-488a-a5e8-466b6dad9385 --name "New Name"

brevo app available-scopes

List every OAuth scope your app can request, grouped by category. Reads the live catalog from Brevo’s OAuth server.

$brevo app available-scopes [--json] [--web]
FlagDescription
--jsonOutput the catalog as JSON instead of a printed table
--webOpen a local browser page at 127.0.0.1:<port> with search and refresh

Examples:

$# Print the catalog grouped by category
$brevo app available-scopes
$
$# Machine-readable output for scripting
$brevo app available-scopes --json | jq '.scopes[].name'
$
$# Searchable browser view
$brevo app available-scopes --web

brevo app scaffold

Generate starter code for an existing app.

$brevo app scaffold [--app-id <id>]
FlagDescription
--app-id <id>Target app ID. Omit to select interactively.
--jsonOutput result as JSON

Generates 11 files including an Express OAuth test server with .env.local pre-populated with your credentials.

Example:

$brevo app scaffold --app-id e22eb778-a2a8-488a-a5e8-466b6dad9385

brevo app start

Start a scaffolded feature server locally.

$brevo app start oauth [--port <port>]
ArgumentDescription
oauthStart the OAuth test server
FlagDescription
--port <port>Override the default port (default: read from app-config.json, fallback 3009)

Run from inside your scaffolded project directory (where app-config.json is). Install dependencies first:

$npm --prefix src/oauth install
$# or: yarn --cwd src/oauth install

Examples:

$# Start on default port
$brevo app start oauth
$
$# Start on a custom port
$brevo app start oauth --port 3000

If you change the port, update your app’s redirect URL to match: brevo app update --redirect-uri http://localhost:3000/auth/callback

Auto-registration. When the resolved port has no matching http://localhost:<port>/... entry on the app, the CLI prompts to register it automatically — approving pushes the new URL to Brevo and updates app-config.json. In non-TTY/CI mode it hard-fails instead of silently mutating the remote app; use brevo app update --redirect-uri to register the URL first.

brevo app delete

Delete an OAuth app. This action cannot be undone.

$brevo app delete [--app-id <id>] [--force]
FlagDescription
--app-id <id>Target app ID. Omit to select interactively.
--forceSkip confirmation prompt
--jsonOutput result as JSON

Example:

$brevo app delete --app-id e22eb778-a2a8-488a-a5e8-466b6dad9385

Claude Code skill

The CLI ships a Claude Code skill so you can drive brevo commands — creating apps, managing scopes, running the local OAuth test server — straight from Claude Code, with the CLI’s conventions and guardrails loaded as context.

$brevo skill:cli install
CommandDescription
brevo skill:cli install [--json]Install the brevo-cli Claude Code skill
brevo skill:cli uninstall [--json]Remove the brevo-cli skill

Once installed, every brevo invocation auto-refreshes the skill when the CLI ships a newer version, so the guidance stays in sync with your installed CLI.

The skill format is specific to Claude Code. Other AI agents (Cursor, Copilot CLI, Gemini, Codex) shouldn’t run brevo skill:cli install — refer to the agent-context/AGENTS.md file bundled with the package instead.

Exit codes

CodeMeaning
0Success
1General error
2Aborted (Ctrl+C or SIGTERM)
3Authentication failure (401)
4Network error (API unreachable)
5Not found (404)

app-config.json schema

The scaffold writes app-config.json to the project root. brevo app update (without flags) pushes this file to Brevo.

1{
2  "appId": "e22eb778-a2a8-488a-a5e8-466b6dad9385",
3  "appName": "my-app",
4  "logoUri": "https://example.com/logo.png",
5  "cliVersion": "0.1.0-alpha.4",
6  "minCliVersion": "0.1.0-alpha.4",
7  "auth": {
8    "type": "private",
9    "scopes": ["contacts:read", "contacts:write", "crm:read", "crm:write"],
10    "redirectUrls": ["http://localhost:3009/auth/callback"]
11  },
12  "distribution": "private"
13}
FieldTypeDescription
appIdstringApp ID assigned by Brevo — do not edit
appNamestringDisplay name of your app
logoUristringOptional http:// or https:// URL to your app’s logo. Empty when not set. Updated via brevo app update --logo-uri <url>.
cliVersionstringCLI version that created this project — set at scaffold time
minCliVersionstringMinimum CLI version required — the CLI warns at startup if the running version is older
auth.typestringAlways private
auth.scopesstring[]OAuth scopes your app requests. New apps default to ["contacts:read", "contacts:write", "crm:read", "crm:write"]. See Scopes for the full catalog.
auth.redirectUrlsstring[]Registered redirect URLs — must match exactly during authorization
distributionstringAlways private

The scaffolded OAuth test server reads auth.scopes from app-config.json and joins it with spaces for the scope= query parameter. If the file is missing or unreadable, it falls back to an internal default that won’t match your app’s registered scopes — keep app-config.json in your project root and unmodified.

Upgrading

$npm install -g @getbrevo/cli@latest

The CLI checks for new versions after each command and prints a banner when one is available. Pass --no-update-notifier or set BREVO_NO_UPDATE_NOTIFIER=1 to suppress it.