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

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 instead.

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.