For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Help CenterAPI KeysStatusSign In
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
  • Getting started
    • Overview
    • Quickstart
    • Authentication
      • API key authentication
        • Overview
        • Quickstart
        • Integration guide
        • CLI reference
      • IP security
    • Rate limits
  • Messaging API
    • Send transactional email
    • Send transactional SMS
    • Send transactional WhatsApp
  • Marketing Platform
    • Manage your contacts
    • Track website activity
    • Send WhatsApp campaigns
    • Weekly event exports
  • Webhooks
    • Getting started
    • Conversations webhooks
    • Payment webhooks
    • Marketing webhooks
    • Transactional webhooks
    • Loyalty webhooks
    • Batched webhooks
    • Secure webhook calls
    • Meetings and phone webhooks
    • Push notification webhooks
    • Sales CRM webhooks
  • Conversations
    • Getting started
    • Customize the chat widget
    • JavaScript API reference
    • REST API reference
    • Conversations webhooks
  • eCommerce
    • Activate eCommerce app
    • Manage product categories
    • Manage products
    • Manage orders
    • Coupon collections
    • eCommerce tracker events
  • Loyalty
    • Overview
    • Set up a program
    • Enroll members
    • Credit & debit points
    • Read member data
    • Best practices
  • Custom Objects
    • Custom objects management
  • Brevo tracker and events
    • Getting started
    • JavaScript implementation
    • REST implementation
    • Legacy tracker documentation
    • Events
  • Accounts and settings
    • Senders and domains
    • User activity logs
    • External feeds
    • Invited users
LogoLogo
Help CenterAPI KeysStatusSign In
On this page
  • Installation
  • Authentication commands
  • brevo login
  • brevo logout
  • brevo whoami
  • App commands
  • brevo app init
  • brevo app create
  • brevo app list
  • brevo app credentials
  • brevo app update
  • brevo app scaffold
  • brevo app start
  • brevo app delete
  • Exit codes
  • Environment variables
  • app-config.json schema
  • Upgrading
Getting startedAuthenticationOAuth 2.0

CLI reference

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

Was this page helpful?
Previous

IP security & authorization

Restrict API access to authorized IP addresses
Next
Built with

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
yarn
$npm install -g @getbrevo/cli

Requirements: Node.js >= 20.15.0

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>]
FlagDescription
--name <name>App name
--distribution <type>Distribution type — private (default)
--redirect-uri <url>Redirect URI — repeatable to add multiple URIs
--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

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 or redirect URLs.

$brevo app update [--app-id <id>] [--name <name>] [--redirect-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.
--yesSkip confirmation prompts
--jsonOutput result as JSON

Behavior:

  • With --name or --redirect-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 appends to existing URLs — it does not replace them
  • 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
$
$# Target a specific app by ID
$brevo app update --app-id e22eb778-a2a8-488a-a5e8-466b6dad9385 --name "New Name"

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

Exit codes

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

Environment variables

VariableDefaultDescription
BREVO_API_KEY—API key for non-interactive authentication (CI/CD). Bypasses brevo login.
BREVO_API_URLhttps://api.brevo.comOverride the Brevo API base URL. Must be HTTPS (HTTP allowed for localhost).
BREVO_OAUTH_PROXY_URLhttps://oauth-cli.brevo.comOverride the CLI login proxy URL. Must be HTTPS (HTTP allowed for localhost).
BREVO_CONFIG_HOME~/.brevo/Override the directory where credentials and cache files are stored.
BREVO_NO_UPDATE_NOTIFIER—Set to 1 to suppress the update-available banner. Also honoured: NO_UPDATE_NOTIFIER=1.
NO_COLOR / FORCE_COLOR—Disable or force ANSI colour output (standard convention).
DEBUG—Enable verbose HTTP and error logging. Equivalent to passing --debug.

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  "cliVersion": "0.1.0-alpha.4",
5  "minCliVersion": "0.1.0-alpha.4",
6  "auth": {
7    "type": "private",
8    "scopes": ["all"],
9    "redirectUrls": ["http://localhost:3009/auth/callback"]
10  },
11  "distribution": "private"
12}
FieldTypeDescription
appIdstringApp ID assigned by Brevo — do not edit
appNamestringDisplay name of your app
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[]Requested scopes — currently ["all"]
auth.redirectUrlsstring[]Registered redirect URLs — must match exactly during authorization
distributionstringAlways private

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.