# 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]` | Deploy a file, directory, or current directory |
| `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](/content/docs/languages/index.html) 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](/content/docs/secrets/index.html) |
| `--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
```