CLI Reference
Command-line tool for deploying and managing your apps.
TerminalCopy
berth [options]
Commands
| Command | Description |
|---|---|
init |
Configure project for OpenBerth (creates .berth.json) |
| `deploy [file | dir]` |
dev [dir] |
Start sandbox with live file sync (hot reload) |
update <id> |
Push code update to a running deployment |
promote <id> |
Promote a sandbox to a production deployment |
list |
List your deployments |
status <id> |
Get deployment details |
logs <id> |
View container logs (--follow for real-time streaming) |
protect <id> |
Set access control (basic_auth, api_key, user, public) |
lock <id> |
Lock deployment (reject updates until unlocked) |
unlock <id> |
Unlock deployment (allow updates again) |
pull <id> |
Download deployment source code to local directory |
destroy <id> |
Remove a deployment |
destroy --all |
Remove all your deployments |
secret set <name> <val> |
Create or update an encrypted secret |
secret list |
List secrets (names + descriptions, never values) |
secret delete <name> |
Delete a secret |
upgrade |
Update CLI to the latest version |
login |
Login via browser (sets up API key automatically) |
config |
Manage CLI configuration |
Init options
| Flag | Default | Description |
|---|---|---|
--yes |
— | Accept all defaults (non-interactive) |
--dir <path> |
current dir | Project directory |
Running berth init creates a .berth.json file in your project with deployment name, TTL, memory limit, port, and access protection settings. These are used automatically by berth deploy and berth dev.
The same file also supports server-side override fields that let you control how OpenBerth builds and runs your app. This is useful when auto-detection picks the wrong framework, or when you’re using an unsupported framework:
| Field | What it overrides | Example |
|---|---|---|
language |
Forces language provider (node, python, go, static) |
"node" |
build |
Build command | "npm run build" |
start |
Start command (production) | "node dist/server.js" |
install |
Dependency install command | "pnpm install --frozen-lockfile" |
dev |
Dev server command (sandbox mode) | "npm run dev -- --host 0.0.0.0 --port $PORT" |
These override fields are read server-side and applied on top of whatever auto-detection finds. If detection fails entirely, providing language + start is enough for OpenBerth to build and run your app. See Supported Languages for more details.
Deploy options
| Flag | Default | Description |
|---|---|---|
--name <name> |
directory name | Custom subdomain name |
--ttl <duration> |
72h |
Time to live: 24h, 7d, 0 for never |
--env <KEY=VAL> |
— | Environment variable (repeatable) |
--memory <limit> |
512m |
Memory limit |
--cpus <limit> |
0.5 |
CPU limit |
--dir <path> |
current dir | Project directory |
--port <port> |
auto-detect | Port your app listens on |
--env-file <path> |
— | Load env vars from file (also auto-loads .env) |
--protect <mode> |
— | Access control: basic_auth, api_key, user |
--users <user,...> |
— | Restrict access to specific users (for user mode) |
--secret <name> |
— | Inject a stored secret (repeatable). See Secrets |
--network-quota <q> |
— | Network transfer quota (e.g. 1g, 5g, 10g) |
Dev options
| Flag | Default | Description |
|---|---|---|
--attach <id> |
— | Reattach file watcher to existing sandbox |
--name <name> |
directory name | Custom subdomain name |
--ttl <duration> |
4h |
Time to live |
--env <KEY=VAL> |
— | Environment variable (repeatable) |
--memory <limit> |
1g |
Memory limit |
--port <port> |
auto-detect | Port override |
--protect <mode> |
— | Access control: basic_auth, api_key, user |
--users <user,...> |
— | Restrict access to specific users (for user mode) |
--secret <name> |
— | Inject a stored secret (repeatable) |
--network-quota <q> |
— | Network transfer quota (e.g. 500m, 1g) |
Logs options
| Flag | Default | Description |
|---|---|---|
--tail <n> |
200 |
Number of lines from the end |
--follow, -f |
— | Stream logs in real time (SSE) |
Upgrade options
| Flag | Description |
|---|---|
--check |
Check for updates without installing |
--version <tag> |
Install a specific version (e.g. v0.1.5) |
The server binary also supports berth-server upgrade with the same flags. On systemd-managed servers, it automatically restarts the service after upgrading.
Examples
TerminalCopy
berth init # Configure project interactively
berth init --yes # Non-interactive with defaults
berth deploy # Deploy current directory
berth deploy App.jsx # Single-file React deploy
berth deploy notes.md # Deploy a Markdown file
berth deploy analysis.ipynb # Deploy a Jupyter notebook
berth dev # Dev sandbox with file watcher
berth dev App.jsx # Single-file dev with hot reload
berth dev --attach abc123 # Reattach to existing sandbox
berth deploy App.jsx --name cool # Custom subdomain
berth update abc123def # Push code update
berth lock abc123def # Lock deployment (reject changes)
berth unlock abc123def # Unlock deployment
berth pull abc123def # Download deployment source
berth pull abc123def --output ./bak # Download to specific directory
berth logs abc123def --tail 50 # View last 50 log lines
berth logs abc123def --follow # Stream logs in real time
berth secret set DB_URL postgres://... --description "Production DB"
berth deploy --secret DB_URL # Inject secret as env var
berth upgrade # Update CLI to latest version
berth upgrade --check # Check for updates without installing
berth config set server https://openberth.example.com
berth config set key bt_your_api_key_here