> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.brevo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server.

# Quickstart

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

An OAuth app lets your application request access to a user's Brevo account with their consent, then call the Brevo API on their behalf — the user authorizes your app once, and your app never handles their password. Under the hood, it's an `app-config.json` with a populated `auth` block (`auth.scopes`, `auth.redirectUris`), unlike a [UI app](/docs/apps-action-links) such as an action link, which uses a `ui_app` block instead.

### Install the CLI and sign in

Follow [Create your first app](/docs/apps-getting-started) to install the CLI and run `brevo login` if you haven't already.

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

```bash
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:

```bash
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:

1. **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](/docs/oauth-scopes) for the full catalog.
2. **Wrote the base project** — `app-config.json` plus `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`.
3. **Scaffolded the Test OAuth App feature** (accepted by default) — a local Express server implementing the full [authorization code flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1), 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](/docs/oauth-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](/docs/cli-reference#claude-code-skill) so Claude can drive `brevo` commands directly.

## Managing your app

```bash
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:

```bash
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](/docs/cli-reference#brevo-app-scaffold).

See the [CLI reference](/docs/cli-reference) for all commands and flags.