BWEZE Docs

CLI

Install @bweze/cli, sign in with a token, and drive projects, services, jobs, domains, SMS and backends from the terminal.

bweze does from a terminal what the dashboard does, for people and for agents alike: tables and prompts at a keyboard, --json and no prompts in scripts and CI.

Install

npm i -g @bweze/cli

It needs Node.js 18 or later. Without installing, prefix any command with npx @bweze/cli. Run bweze --help for the command groups and bweze <group> --help for one group's commands and flags.

Sign in

Create an API token in BWEZE Platform under Manage workspace › API tokens (a secret bw_sk_... token), then:

bweze login --api-key bw_sk_...   # checks the token with GET /v1/me, then saves it
bweze whoami                      # who the CLI acts as
bweze current                     # the workspace and project it is pointed at
bweze logout                      # forget the saved token

bweze login with no flags asks you to paste the token. The token is saved in ~/.bweze/credentials.json, readable only by you; settings go in ~/.bweze/config.json.

In CI, skip the login and pass the token in the environment:

VariableWhat it does
BWEZE_ACCESS_TOKENThe token to use, instead of the saved one
BWEZE_API_KEYThe token bweze sms and bweze domain use (they ignore the saved login)
BWEZE_API_URLThe API to talk to (default https://api.bweze.com); --api-url does the same for one command
BWEZE_PROJECT_ID, BWEZE_ORG_IDThe project and workspace to act on, instead of the linked ones
BWEZE_TELEMETRY_DISABLED=1Turns off the CLI's usage telemetry (DO_NOT_TRACK works too)

Commands that act on one project's backend (db, storage, functions, secrets, schedules, logs) use the project linked to the current directory:

bweze list                       # every workspace and its projects
bweze link --project-id <id>     # writes ./.bweze/project.json

In scripts and agents

  • --json prints machine-readable output and never prompts; a command that would need an answer fails instead of hanging.
  • -y, --yes accepts confirmation prompts.
  • The exit code says what went wrong:
CodeMeaning
0Done
1Any other error
2Not signed in, or the command is not available on BWEZE
3No project linked to this directory
4Not found
5Permission denied (see API tokens)

bweze jobs run exits with the code of the command it ran.

The approval guard

With BWEZE_GUARD=1 set (or bweze link --guard for one project), destructive operations stop before they run: dropping or truncating tables, DELETE or UPDATE without a WHERE, changing row-level security, deleting a project, bucket, function or secret, rotating a key. The CLI shows a brief on a page on localhost and runs the command only once a person approves it there.

An agent explains itself to the approver with --reason (what and why), --impact (who or what is affected, whether it can be undone) and --recommendation. --flag-destructive asks for approval on a command the guard would let through; it can never wave one through.

Commands

Projects

bweze projects list
bweze projects create acme-web -t frontend        # or -t backend
bweze projects get --project <id>
bweze projects update --project <id> --name acme-site
bweze projects delete --project <id>
bweze projects exec <projectId> ls -la /app       # one command in the running container

exec is the Terminal: 30 seconds, 256 KB of output, and it needs the terminal:exec permission.

Services and jobs

bweze services list <projectId>
bweze services show <serviceId>
bweze services set <serviceId> --start-command "node dist/server.js" --port 8080
bweze services set <serviceId> --pre-deploy-command "npm run migrate"
bweze services set <serviceId> --schedule "0 2 * * *" --time-limit 30m   # a cron job

bweze jobs run <serviceId> -- npm run backfill --since 2026-11-01
bweze jobs run <serviceId> -d -- ./scripts/reindex.sh   # start it and return
bweze jobs list <serviceId>
bweze jobs logs <serviceId> <jobId> --follow
bweze jobs cancel <serviceId> <jobId>

See Services and Jobs and cron.

Domains

bweze projects domains search acme
bweze projects domains buy <projectId> acme.rw \
  --name "Aline Uwase" --email [email protected] --street "KG 7 Ave" --city Kigali --country RW
bweze projects domains connect <projectId> app.example.com
bweze projects domains verify <domainId>
bweze projects domains list <projectId>
bweze domain check acme                           # is acme.rw free?

buy spends from the wallet; it shows the price and the owner first. See Domains.

Scheduled URLs and the firewall

bweze projects cron list <projectId>
bweze projects cron create <projectId> -n nightly-report -s "0 6 * * *" -u https://acme.bweze.app/api/report
bweze projects cron disable <jobId>

bweze projects firewall list <projectId>
bweze projects firewall add <projectId> -a block -c 203.0.113.0/24 --note "scraper"
bweze projects firewall delete <ruleId>

projects cron calls a URL on a schedule. To run a command on a schedule, make the service a cron job instead.

SMS

export BWEZE_API_KEY=bw_sk_...
bweze sms preview --body "Your code is 4821"            # segments and encoding, no charge
bweze sms send --to +250788123456 --body "Your code is 4821" --confirm

Without --confirm, send only previews. See Messaging.

Backends

These act on the linked project's backend. See Backends.

GroupCommands
dbquery <sql>, tables, functions, indexes, policies, triggers, rpc <fn>, export, import <file>, migrations list|new|up
storagebuckets, create-bucket <name>, delete-bucket <name>, list-objects <bucket>, upload <file>, download <key>, s3-keys list|create|delete
functionslist, code <slug>, deploy <slug> --file, invoke <slug>, delete <slug>
secretslist, get <key>, add <key> <value>, update <key>, delete <key>, rotate api-key|anon-key
scheduleslist, get <id>, create --name --cron --url --method, update <id>, delete <id>, logs <id>
logs <source>bweze.logs, postgREST.logs, postgres.logs, function.logs, function-deploy.logs
bweze db query "select id, email from users limit 10"
bweze db migrations new add_orders && bweze db migrations up
bweze db export --format sql -o backup.sql
bweze storage upload ./logo.png --bucket public --key brand/logo.png

Not on BWEZE yet

branch, diagnose, billing, usage, backups, compute and orgs members print "not available on BWEZE" and exit with code 2.

On this page