bermooda CLI

From zero to shop in one command

bermooda installs, runs, updates, and extends your shop. Themes, plugins, and agent setup are commands, not chores.

npm i -g @bermooda/cli@latest

Node.js ≥ 24 · MIT licensed

~/my-shop@bermooda/cli

$ bermooda install --local --dir ./my-shop -y

┌ bermooda install

ℹ Downloading bermooda@latest from npm…

✔ App source ready (npm, ref [email protected])

✔ Dependencies installed

✔ Wrote .env

✔ Wrote bermooda.config.js

✔ Database ready

✔ Admin user and store configured

ℹ Installing default theme and plugins…

└ Shop ready at ~/my-shop

What it does

Lifecycle in your terminal.

The CLI owns the parts of running a shop that happen outside the admin: setup, upgrades, extensions, and wiring up agents. Catalog, settings, and orders stay in the admin and the Admin REST API.

bermooda install
Scaffold a shop
Downloads the app, installs deps, writes .env and bermooda.config.js, migrates the database, and creates your admin and store.
bermooda dev · start
Run it
dev serves storefront, admin, and API on port 3000. start runs production and builds first if build/ is missing.
bermooda update
Stay current
Fast-forwards a git checkout or merges core paths from the latest release, then reinstalls and migrates.
bermooda theme
Swap the storefront
Add, update, remove, or list themes from npm, a local path, git, or a tarball. --activate switches to it.
bermooda plugin
Hook the engine
Same shape as themes. --enable turns a plugin on in shop settings the moment it lands.
bermooda mcp init
Hand it to an agent
Writes .cursor/mcp.json with your shop URL and bootstrap API key, so Cursor or Claude can drive the Admin API.

install

Laptop or server. Same command.

Run it bare and it asks what it needs. Pass -y and flags and it runs unattended, in CI or a provisioning script.

01
Download the app from npm, a git ref, or a local checkout
02
npm install
03
Write .env and bermooda.config.js
04
Generate Prisma client and run migrations
05
Create the admin user and store
06
Install the default theme and search plugin

localSQLite

# SQLite, sensible defaults, no prompts
$ bermooda install --local --dir ./my-shop -y \
    --admin-email [email protected] \
    --store-name 'Demo Shop'

serverPostgreSQL

# PostgreSQL, your domain, demo catalog
$ bermooda install --server --dir /srv/shop -y \
    --database-url "$DATABASE_URL" \
    --base-url https://shop.example.com \
    --from-email 'Shop <[email protected]>' \
    --admin-email [email protected] \
    --admin-password "$ADMIN_PASSWORD" \
    --with-demo

install flags

--local / --server
Install profile: SQLite or PostgreSQL defaults
--dir <path>
Target directory
--ref <tag|branch>
Install a specific app ref from GitHub
--source <path>
Use a local app checkout, no network
--db, --database-url
Pick the database and connection string
--base-url, --from-email
Public URL and transactional sender
--skip-deps, --skip-db
Skip npm install or migrate and seed
--force, --force-env
Allow a non-empty dir, overwrite .env

theme · plugin

Extensions from anywhere. Safely.

Themes land in app/themes/*, plugins in app/plugins/*. Both commands share one shape: add, update, remove, list.

sourcesnpm · path · git · tarball

# npm (default), optionally pinned
$ bermooda plugin add @bermooda/plugin-subscriptions 1.2.0

# a folder you are hacking on
$ bermooda theme add my-theme --path ./packages/my-theme

# a git ref or an HTTPS tarball
$ bermooda plugin add my-plugin --git https://github.com/org/plugin.git#v1
$ bermooda plugin add my-plugin --tarball https://example.com/plugin.tgz

package.json

{
  "name": "@acme/bermooda-plugin-loyalty",
  "bermooda": {
    "id": "loyalty",
    "engine": ">=0.13.0"
  }
}

Engine checked first
Each package declares a bermooda.engine semver range. Incompatible versions are rejected before anything is copied.
Scripts off by default
Extension dependencies install with --ignore-scripts. Opt specific packages in with BERMOODA_EXTENSION_INSTALL_SCRIPTS.
Backups on update
update copies the previous version to .bermooda/backups before replacing it, so a bad release is one move away from undone.

update

Upgrades you can preview.

bermooda update pulls the latest release, reinstalls dependencies, and runs migrations. Add --dry-run to see the plan first, or --ref to pin a version.

git-ffShop is a git checkout
Fetches tags and fast-forwards. If you changed core files, it stops and tells you instead of guessing.
tarball-mergePlain directory
Downloads the release and merges core paths. Your themes, plugins, .env, and config stay put.

The CLI keeps itself current too: bermooda upgrade.

updateplan, then apply

$ bermooda update --dry-run
{
  "shopRoot": "/srv/shop",
  "targetRef": "v0.14.0",
  "strategy": "tarball-merge",
  "previousRef": "[email protected]"
}
$ bermooda update
✔ Tarball merge complete (412 paths, source v0.14.0)
✔ Database ready
✔ Shop updated to v0.14.0

.cursor/mcp.jsonbermooda mcp init

{
  "mcpServers": {
    "bermooda": {
      "command": "npx",
      "args": ["-y", "bermooda-mcp"],
      "env": {
        "BERMOODA_URL": "http://localhost:3000",
        "BERMOODA_API_KEY": "berm_…"
      }
    }
  }
}

mcp init

Built for agents, too.

One command connects Cursor to your shop. It reads the bootstrap API key written at install and merges a bermooda server into your MCP config. Paste the same block into Claude Desktop.

The agent works through the same Admin API as the admin UI, with the same scopes. No side channel into the database.

Agents guide →

Scripting

Quiet when piped. Honest on exit.

Every command takes --cwd, -y, --json, and --verbose. JSON output where it matters, and exit codes that tell your pipeline what broke.

exit codes

0
Success
1
User or project error
2
Network or download
3
Dependency install
4
Database or bootstrap
130
Interrupted

Reference

Every command.

Full flags in the docs →

Shop

$ bermooda install [--local|--server]
Download the app, deps, env, DB, admin, and store
$ bermooda update [--ref] [--dry-run]
Update the shop to the latest app version
$ bermooda dev [--port]
Start the development server
$ bermooda start
Run production, building first if needed

Extensions

$ bermooda theme add|update|remove|list
Manage app/themes/*
$ bermooda plugin add|update|remove|list
Manage app/plugins/*
$ bermooda mcp init
Write MCP config for this shop

CLI

$ bermooda version [--cli|--shop]
Show CLI and shop versions
$ bermooda upgrade
Upgrade @bermooda/cli itself
$ bermooda help [command]
Built-in help for any command

Three lines to a running shop.

Answer a few prompts, open localhost:3000, and start selling.

terminalNode.js ≥ 24

$ npm i -g @bermooda/cli@latest
$ bermooda install
$ cd bermooda && bermooda dev

Quick start CLI docs