CLI

The norbelys CLI puts your whole Norbelys workspace in your terminal. People, campaigns, senders, segments, deliverability, analytics — each is a command, and it stays perfectly in step with the platform because every command is generated from the same definitions the product itself uses. Sign in once and drive everything from the shell or a script.

The CLI works on the same Norbelys workspace as the dashboard and the API — the same fields, the same limits, the same safety rails. Whatever you can do in the app, you can do here, scripted.

Install

Run the installer

curl -fsSL https://cli.norbelys.com/install | sh

It downloads a single self-contained bundle, drops a norbelys launcher in ~/.norbelys/bin, and adds that to your PATH. The CLI runs on Bun or Node; if you have neither, the installer sets Bun up for you. Override the location with NORBELYS_INSTALL.

Open a new terminal

So the updated PATH takes effect (or run the export PATH=… line the installer prints). Verify:

norbelys version

norbelys login

See Sign in below for the browser flow and the API-key alternative.

On a machine you’d rather not run a compiled binary on, the CLI is just a JS bundle — the launcher runs it with your existing bun/node. Nothing is hidden.

Two credentials work, and both authenticate the exact same way (Authorization: Bearer …). The CLI stores them in ~/.config/norbelys/config.json, readable only by you (mode 0600).

Four steps: you run login and a local listener opens the browser; you approve in Clerk and pick the org; Clerk redirects to 127.0.0.1 with a one-time code; the CLI exchanges it for a ~24h token that auto-refreshes. — norbelys login opens your browser once; the CLI then keeps the session fresh on its own.

Method	Best for	Command
Browser (OAuth 2.1 + PKCE)	you, on a laptop	`norbelys login`
Org-scoped API key (`ak_…`)	CI, servers, scripts	`norbelys login --api-key ak_…`
Environment variable	ephemeral CI jobs	`export NORBELYS_API_KEY=ak_…`

# Opens your browser; you approve the consent screen and pick the org. Done.
norbelys login
norbelys whoami

# Create the key in the dashboard → Settings → API keys.
norbelys login --api-key ak_live_…

# No stored login needed — the env var short-circuits everything.
export NORBELYS_API_KEY=ak_live_…
norbelys people list

norbelys whoami shows the active organization, the auth method, and the profile.
norbelys logout revokes the session and deletes the stored credential.
Browser sessions last about 24 hours and refresh automatically — you sign in once and the CLI keeps the token fresh until you log out. API keys never expire.

How commands work

Commands mirror the API’s procedures, folded into a tree: norbelys <resource> <verb> [id] [--flags]. Nested paths become nested commands (programs senders add). --help at any level lists what’s there, and every flag is generated from the procedure’s own schema.

norbelys people list --limit 20 --status active
norbelys people find con_… --expand timeline
norbelys programs list
norbelys programs audit prg_…
norbelys senders list

norbelys people create --email [email protected] --givenName Ada
norbelys people update con_… --familyName Lovelace
norbelys segments create --name Founders --definition.match all \
  --definition.conditions '[{"field":"email_sendable","op":"is_true"}]'

norbelys programs launch prog_…      # confirms first — starts real sending
norbelys people archive con_… --yes  # skip the prompt in scripts

Positional argument = path parameter — norbelys people find <id>.
Flags = body/query fields, named exactly as in the API (--givenName, --status).

Nested fields are flags too — --<field>.<sub>, so nothing routine needs hand-written JSON:

norbelys senders create --transportMode smtp \
  --fromEmail [email protected] --fromName "Ada from Acme" \
  --smtp.host smtp.acme.com --smtp.port 465 --smtp.security ssl --smtp.password "$SMTP_PASS"

norbelys analytics query --query program_funnel --params.program prg_…

--help lists every nested flag, so the shape is never a guess.

Open key/value fields take pairs — --customFields "company=Acme,city=Bogotá".
Lists are comma-separated — --expand steps,senders (repeating a flag keeps only the last).
--data carries a whole body when you want one: inline '{…}', @file.json, or - for stdin. Individual flags override it per field, so you can keep a base body in a file and change one value on the command line.
norbelys api <METHOD> <path> calls any endpoint directly, like curl with your auth already attached: norbelys api GET /organization.

Inputs are validated against the same schemas as the API before the request goes out, so a wrong field is caught locally with the exact error — no round-trip to find out.

What you can reach

Group	Commands	Does
People	`people list/find/create/update/archive/import`	your CRM leads, custom fields, CSV import
Campaigns	`programs …` (`create`, `audit`, `launch`, `pause`, `senders add`, `enroll`)	sequences, Liquid QA, senders, enrollment
Audience	`segments …`, `groups …`	dynamic segments + static lists
Senders	`senders list/create/update`	mailboxes and their config
Deliverability	`domains …`, `verify email`	DMARC domains, email verification
Messages	`messages list/find/create`	the message log + one-off sends
Insight	`analytics query`, `organization pulse/usage`	analytics, the workspace briefing, plan usage
Account	`login`, `logout`, `whoami`, `version`, `upgrade`, `api`	auth + housekeeping

Run norbelys --help for the full grouped list, or norbelys <group> --help to drill in.

Output & scripting

Human-friendly tables by default; add --json for raw JSON on stdout. Everything non-data — prompts, spinners, notices — goes to stderr, so pipelines stay clean.

norbelys people list --json | jq -r '.data[].email'

Exit codes are stable: 0 success, non-zero on error; auth failures print a clear re-authenticate hint.
--json silences color, tables, and the update notice — safe to parse.

Anything destructive or outward-facing — deletes, messages create (a real email, even a test), programs bulk, programs launch/resume — asks you to confirm. Pass --yes to skip the prompt. In a non-interactive shell these fail closed unless --yes is given, so a piped script can never silently blast mail.

Audit a campaign before launch

programs audit is a read-only preflight. It expands the saved cadence and mailboxes, checks that the campaign is genuinely complete, validates Liquid in the subject, preheader, and body, and renders every saved version against a bounded sample of enrolled leads. It sends nothing.

# Human-readable readiness, findings, field coverage, and rendered inbox previews
norbelys programs audit prg_…

# Test against one specific contact, or increase the sample (maximum 10)
norbelys programs audit prg_… --person con_…
norbelys programs audit prg_… --sample 10

# Stable machine-readable report for CI
norbelys programs audit prg_… --json

The report catches the failures that a campaign shell cannot show: missing arms or copy, subjects/preheaders that never personalize, Liquid that fails on real data, low-coverage merge fields, disabled tracking/unsubscribe, and a full UTM URL displayed as link text. A tracked link keeps its complete URL in href; the visible label can stay short, such as getarbol.com.

Import a CSV

Bringing a lead list in from a CSV is one command. It maps common columns automatically (Email, First Name, Last Name, Phone), and --map handles headers that don’t match.

# Recognized columns map themselves; anything else becomes a custom field.
norbelys people import leads.csv

# field=Column — point each person field at your CSV's header.
norbelys people import leads.csv \
  --map "email=Correo,givenName=Nombre,familyName=Apellido"

# See exactly how every column maps, plus a sample — imports nothing.
norbelys people import leads.csv --dry-run

Column mapping:
  Correo                   → email
  Nombre                   → givenName
  Apellido                 → familyName
  Empresa                  → customFields.empresa (custom)
  Cel                      → telephone

Columns you don’t map become custom fields (keyed by the column name); pass --skip-unmapped to drop them instead.
Add everyone to a list or campaign as they import: --group grp_… / --campaign prog_….
Rows without an email are skipped; large files are sent in chunks, and new addresses are verified in the background.

Multiple organizations

Each credential is scoped to one organization, so multi-org means one profile per org:

norbelys login --profile acme          # sign a second org in
norbelys people list --profile acme     # one-off against it
norbelys whoami --profile acme          # confirm which org it points at

Without --profile, commands use your default profile (or NORBELYS_PROFILE).

Staying current

norbelys version        # your version, and whether a newer one exists
norbelys upgrade        # update to the latest

The CLI also checks for a new release about once a day and prints a one-line notice to stderr when there is one. Silence it with --json, a CI environment, or NORBELYS_NO_UPDATE_CHECK=1.

Troubleshooting

norbelys: command not found (right after install)

Open a new terminal so the updated PATH loads, or run the export PATH="…/.norbelys/bin:$PATH" line the installer printed. Then norbelys version.

It says no_active_organization

Your credential isn’t scoped to an organization. For an API key, create an org-scoped key (Settings → API keys). For browser login, make sure you picked an organization on the consent screen — that choice becomes the token’s org.

Using it in CI / a container

Set NORBELYS_API_KEY=ak_… in the environment — it short-circuits login entirely, so there’s no interactive step and nothing written to disk. Add --yes to any destructive command.

How it works

The CLI, the MCP server, Norbe, and the dashboard all act on one workspace through one API, with the same kind of credential. The CLI can only do what your credential can, on the organization it belongs to — nothing more. Pick whichever surface fits the task; they never disagree.

Prefer AI agents?

The same API is available to Claude, Cursor, and any MCP client via the Norbelys MCP server.

Get started

Reference

Install

How commands work

What you can reach

Output & scripting

Audit a campaign before launch

Import a CSV

Multiple organizations

Staying current

Troubleshooting

How it works

Prefer AI agents?

​Install

​Sign in

​How commands work

​What you can reach

​Output & scripting

​Audit a campaign before launch

​Import a CSV

​Multiple organizations

​Staying current

​Troubleshooting

​How it works

Prefer AI agents?

Install

Sign in

How commands work

What you can reach

Output & scripting

Audit a campaign before launch

Import a CSV

Multiple organizations

Staying current

Troubleshooting

How it works