Quickstart | Brevo API Documentation

The Brevo CLI handles app creation, credential management, and local testing. This quickstart walks through the fastest path to a working OAuth flow.

Install the CLI

npm

yarn

Homebrew

$ npm install -g @getbrevo/cli

Requires Node.js >= 20.15.0 (Homebrew installs Node automatically). Verify the installation:

$ brevo --version

Log in to Brevo

$ brevo login

The CLI prompts you to choose between browser sign-in (default) and API key. Browser sign-in opens oauth-cli.brevo.com — credentials are saved to ~/.brevo/credentials.json.

Welcome to Brevo CLI
──────────────────────────────────────
? How would you like to authenticate? Browser (sign in through your browser)
  Opening your browser to log you in...
  Waiting for login to complete (Ctrl+C to cancel)...
✓ Login complete. Credentials saved to /Users/you/.brevo/credentials.json.
✓ Authenticated as you@example.com

For non-interactive environments (CI/CD), set the BREVO_API_KEY environment variable instead of running brevo login.

Create your app and scaffold starter code

$ brevo app init

The guided setup prompts for an app name, logo URL, distribution type, app type, and OAuth callback URL; writes the base project; then asks separately whether to scaffold the OAuth test server. Use http://localhost:3009/auth/callback as your callback URL for local development.

Brevo CLI — Quick Setup
──────────────────────────────────────
✓ Already authenticated.
  Step 2: Create your first app
? App name: my-app
? App logo URL (optional — leave blank to skip):
? Distribution type? Private  (Used exclusively by your organisation)
? What type of app are you building? OAuth app  (Authorize against Brevo and call the API on a user’s behalf)
? OAuth callback URL — where users are sent after authorizing your app: http://localhost:3009/auth/callback
? Add another redirect URL? (y/N) No
? Output directory: ./my-app
  ┌───────────────────────────────────────────────────────────────────────────┐
  │ App created                                                               │
  ├───────────────────────────────────────────────────────────────────────────┤
  │ App name:       my-app                                                    │
  │ App ID:         e22eb778-a2a8-488a-a5e8-466b6dad9385                      │
  │ Client ID:      8768a0ad5801806c7946ca7c29648cc2                          │
  │ Client secret:  [hidden — run `brevo app credentials --reveal-secret`]    │
  │ Redirect URL 1: http://localhost:3009/auth/callback                       │
  │ App version:    1                                                         │
  │ Default scopes: contacts:read, contacts:write, crm:read, crm:write        │
  │                                                                           │
  │ You can add more scopes later by editing `auth.scopes` in app-config.json │
  │ and running `brevo app upload`.                                           │
  └───────────────────────────────────────────────────────────────────────────┘
✓ Project structure created (5 files)
    ├── .gitignore
    ├── AGENTS.md
    ├── app-config.json
    ├── CLAUDE.md
    └── README.md
? Scaffold the Test OAuth App? (Y/n) Yes
✓ Feature scaffolded (6 files)
    └── src/
        └── oauth/
            ├── .env.example
            ├── .env.local
            ├── handler.js
            ├── package.json
            ├── server.js
            └── token-store.js
  ┌─────────────────────────────────────────┐
  │ Next steps                              │
  ├─────────────────────────────────────────┤
  │ 1. yarn --cwd src/oauth                 │
  │    (or: npm --prefix src/oauth install) │
  │ 2. brevo app start oauth                │
  └─────────────────────────────────────────┘
  Tip: list available scopes with `brevo app available-scopes`. Update scopes by editing `auth.scopes` in app-config.json and running `brevo app upload`.
  All set! Run `brevo app start oauth` to test your OAuth flow, or `brevo --help` to see all commands.

app-config.json, app version, and the box layout above all reflect the app-store CLI shipped in v2.1.0. Declining “Scaffold the Test OAuth App?” leaves the base project only — run brevo app scaffold afterward to add it.

Your client_id and client_secret are written to src/oauth/.env.local automatically. This file is gitignored — never commit it.

Start the test server

Install the test server’s dependencies, then start it:

$ cd my-app
$ npm --prefix src/oauth install
$ brevo app start oauth

Your browser opens at http://localhost:3009. Click Start OAuth Flow, sign in with a Brevo account, and your tokens appear masked in the browser — click to reveal them.

Starting oauth...
Test server running at http://localhost:3009
Opening browser...

If the port you’re using isn’t registered as a redirect URL on your app, the CLI will prompt you to add it automatically. Approve to continue — it updates your app and app-config.json in one step.

What just happened

brevo app init did three things:

Registered an OAuth app on Brevo, issuing a client_id and client_secret. New apps are seeded with the scopes contacts:read, contacts:write, crm:read, crm:write — see Scopes for the full catalog.
Wrote the base project — app-config.json plus .gitignore, AGENTS.md, CLAUDE.md, README.md.
Scaffolded the Test OAuth App feature (accepted by default) — a local Express server implementing the full authorization code flow, plus src/oauth/.env.local with your credentials (gitignored, chmod 600):
- GET /auth/login — builds the authorization URL (reads auth.scopes from app-config.json) and redirects to oauth.brevo.com
- GET /auth/callback — validates state, exchanges the authorization code for tokens
- GET /auth/refresh — exchanges the refresh token for a new access token

This server is a reference implementation for local testing. To implement OAuth in your real application, follow the Integration guide.

Works out of the box with AI coding tools. The scaffold ships CLAUDE.md (Claude Code) and AGENTS.md (GitHub Copilot, Cursor, and similar) pre-populated with the OAuth flow, endpoints, and run instructions — your AI assistant understands the project with no extra context. For Claude Code, brevo skill:cli install also adds a CLI skill so Claude can drive brevo commands directly.

Managing your app

$ brevo app list                                           # list all apps
$ brevo app credentials --app-id <id> --reveal-secret     # view credentials
$ brevo app available-scopes                              # browse the scope catalog
$ brevo app delete --app-id <id>                          # delete app

To rename the app, add a redirect URL, or add a scope, edit the corresponding field in app-config.json (appName, auth.redirectUris, auth.scopes) and push the change:

$ brevo app upload

Lost the project folder, or setting up on a new machine? brevo app scaffold --app-id <id> recovers it — see Recovering a project.

See the CLI reference for all commands and flags.