CLI

Installation

# npm
npm install -g @bunbase/cli

# bun
bun install -g @bunbase/cli

# one-shot (no install)
bunx @bunbase/cli <command>

Verify:

bunbase --version

---

Commands

Command	Description
bunbase init	Scaffold a new BunBase project
bunbase backup	Download a database backup
bunbase restore <file>	Upload and restore a backup
bunbase deploy	Deploy to a VPS via rsync + SSH
bunbase update	Update the CLI to the latest version

Run bunbase <command> --help for per-command options.

---

bunbase init

Scaffold a new self-hosted BunBase deployment in the target directory.

bunbase init
bunbase init --dir ./myapp --name myapp --port 3000

Creates:

File	Purpose
.env	Server environment variables with generated secrets
docker-compose.yml	Run BunBase as a Docker service
bunbase.config.ts	CLI config (URL, admin key, deploy settings)
data/	Persistent data directory (mounted by Docker)

Options:

Flag	Default	Description
--dir <path>	Current directory	Target directory
--name <name>	Directory name	Project name
--port <port>	3000	Server port

Existing files are never overwritten — re-running init is safe.

---

bunbase backup

Download a full database backup from your running server.

bunbase backup
bunbase backup --url https://api.example.com --key <admin-key> --out my-backup.db

Options:

Flag	Default	Description
--url <url>	Config / http://localhost:3000	Server URL
--key <key>	Config / BUNBASE_ADMIN_KEY env	Admin key
--out <file>	bunbase-backup-<timestamp>.db	Output filename

---

bunbase restore <file>

Upload a backup file and restore the database. The server restarts automatically.

bunbase restore bunbase-backup-1234567890.db
bunbase restore bunbase-backup-1234567890.db --yes  # skip confirmation

Options:

Flag	Default	Description
--url <url>	Config / http://localhost:3000	Server URL
--key <key>	Config / BUNBASE_ADMIN_KEY env	Admin key
--yes	false	Skip confirmation prompt

Destructive. This replaces the live database. You will be asked to confirm unless --yes is passed.

---

bunbase deploy

Sync your project to a remote VPS via rsync, then SSH in to run the restart command.

bunbase deploy
bunbase deploy --host user@vps.example.com --path /opt/bunbase
bunbase deploy --dry-run  # print commands without executing

Options:

Flag	Default	Description
--host <user@host>	Config deploy.host	SSH target
--path <path>	Config deploy.path / /opt/bunbase	Remote path
--restart <cmd>	Config deploy.restart / pm2 restart bunbase	Post-sync command
--dry-run	false	Print commands only

Automatically excluded from rsync: .git, node_modules, data/, *.db, *.db-shm, *.db-wal, dist/, .env

.env is never synced — manage secrets on the server separately.

---

bunbase update

Update the CLI to the latest version published on npm.

bunbase update

Detects which package manager installed the CLI (Bun, npm, or pnpm) and runs the appropriate global install command.

---

Config file

Place a bunbase.config.ts (or .json) in your project root to avoid repeating flags:

import type { BunBaseConfig } from '@bunbase/cli';

const config: BunBaseConfig = {
  url: 'https://api.example.com',
  adminKey: process.env.BUNBASE_ADMIN_KEY,

  deploy: {
    host: 'user@vps.example.com',
    path: '/opt/bunbase',
    restart: 'cd /opt/bunbase && docker compose pull && docker compose up -d',
  },
};

export default config;

Resolution order: bunbase.config.ts → bunbase.config.js → bunbase.config.mjs → bunbase.config.json

Field priority: CLI flag → config file → built-in default

---

Auto update check

After every command, the CLI silently checks npm for a newer version (at most once per 24 hours). If one is available, a notice is printed:

Update available! 0.14.0 → 0.14.1
Run bunbase update to upgrade.

The check result is cached in ~/.bunbase/update-check.json and never blocks command execution.