Skip to navigation
Overview

Create your first app

Install the Brevo CLI and create your first app
View as Markdown

Every Brevo App starts with the Brevo CLI (@getbrevo/cli).

Works with Claude Code. Every step below can be driven straight from Claude Code. Run brevo skill:cli install once to add the Brevo CLI skill.

Install the CLI

npm install -g @getbrevo/cli

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

Sign in

brevo login

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

Create an app

brevo app init

Guided setup: authenticate, create an app, and optionally scaffold starter code, in one flow. No flags; it prompts for app name, distribution type (private or public; public also asks you to agree to the Brevo Developer Terms), app type, OAuth flow (private OAuth apps only), OAuth callback URL, output directory, and whether to scaffold the Test OAuth App feature.

For scripted or automated flows, use brevo app create with flags instead. See the CLI reference.

Your app’s configuration

brevo app init (or brevo app create) writes an app-config.json file to your project. This file is your app. It’s the single source of truth: edit it, then run brevo app upload to push the change to Brevo. brevo app upload always fetches the server’s current state first and shows you a diff before pushing anything.

A few top-level fields are shared by every app, regardless of type:

FieldDescription
app_idAssigned by Brevo when the app is created; don’t edit
app_nameDisplay name of your app
versionRead-only; tracks the app-store API version, updated automatically on each upload
logo_uriOptional URL to your app’s logo
distribution_typeprivate or public; set at creation and immutable. See Private and public apps.
app_typeOptional, informational label — oauth, ui, or function. Never sent to Brevo; the blocks below are what actually determine the type.

Private or public? A private app can only be authorized or installed by users within your own Brevo organization. A public app can be authorized by any Brevo account once Brevo has reviewed and approved it, and you distribute it yourself, for example with an install link in your product. Public apps must be consent-based OAuth apps; UI apps can’t be public for now. See Private and public apps.

What the rest of the file looks like depends on the app type you chose when creating it:

  • OAuth app: a populated auth block (auth.scopes, auth.redirect_uris) and no ui_app key at all. This is what lets your app authenticate on a user’s behalf. See Authentication & scopes.
  • UI app: the opposite shape, an empty auth: {} and a populated ui_app block instead. See Action links for a full example.

The presence of the ui_app key is what tells Brevo which kind of app this is. Never populate both auth and ui_app in the same file.

Next steps

Authentication & scopes

How OAuth apps authorize on behalf of a user, and the scopes they can request.

CLI reference

Every brevo command and flag.