CLI

boatramp is one binary: the server (serve) and every client command. This page documents each command. Any command also prints its own flags with boatramp <command> --help, and group commands list their sub-actions with boatramp <command> help.

Precedence for any overridable value: flag / environment variable > config file > built-in default. Project commands read project.cfg; serve reads boatramp.cfg.

Global flags

Common client flags

Most client commands accept these, so the per-command tables below list only the flags unique to each command:

Commands

Exit status is 0 on success and non-zero on failure; see Errors & exit codes.

boatramp serve

Run the server: selects backends, TLS, auth, and (with the cluster feature) cluster mode. The cluster: and compute: sections are configured in boatramp.cfg, not on the command line.

The config file (--config <path>, default boatramp.cfg) is RON or JSON — auto-detected by extension; pass --format <ron|json> to override (e.g. a Nickel-generated config on a non-.json path). See Author configs in RON or JSON.

Address, storage, cache

Authentication

Warning: with no root key, control-plane auth is disabled. Under the default multi-tenant posture, serve refuses to start that way on a non-loopback --addr. Configure a key, bind 127.0.0.1, or select a looser security posture.

TLS

Uploads, serving, cluster

boatramp serve --config boatramp.cfg \
  --addr 0.0.0.0:8080 --tls acme --acme-domain pad.example.com

boatramp project

Manage projects — the Workspace that owns sites, functions, and compute, and is the tenant boundary a handler’s row-level scope resolves to. Takes the common --server flag.

boatramp apply

Reconcile a whole project — its member sites (each a content dir + optional build + routing + config), top-level functions, and compute workloads — from one declarative RON manifest, in a single pass. Sites reuse the content-addressed sync flow (upload only the missing blobs, then activate); functions and compute are create-or-replace. apply is pure upsert and never prunes, so declarative and imperative (CLI/API) management coexist. See Declare a project with apply.

The target project is the manifest’s project: field, else the global --project / default.

boatramp migrate

Migrate a pre-0.2.0 control-plane store to the project-scoped layout (mutable per-name records re-key under project/<proj>/…; no content-addressed body moves). The migration is online, idempotent, and resumable. serve refuses an unmigrated store unless started with --auto-migrate. See Upgrade a store to project scoping.

A plain boatramp migrate (no --stage) copies and finalizes in one shot.

Three unrelated migrate verbs. Don’t confuse them:

• boatramp migrate (this top-level command) — the one-time pre-0.2.0 control-plane store re-key to the project-scoped layout.
• boatramp blob migrate — an offline, node-local copy of the whole blob backend from one storage config to another (fs→cloud, region→region).
• boatramp config migrate — a client-side upgrade of an apply manifest to the current schema version.

They share only the word “migrate”; each help text cross-disambiguates.

boatramp sync

Build (optional) and publish a folder as a new atomic deployment. Argument: [PATH] — the directory to publish (defaults to build.output, then .).

boatramp build

Run the configured build command only.

boatramp bundle

Bundle JS/TS (Rolldown) + CSS (lightningcss) in-process. Needs the bundler feature; configured by the bundle section of project.cfg.

boatramp compose

Fuse a root (“edge”) component with one or more plugin components into a single linked component, in-process — no external toolchain, no network hop. The fused component’s exports are unchanged (still e.g. wasi:http/incoming-handler); only the imports a plugin satisfies are linked internally, while host imports (wasi:http, sql, kv, …) stay imported for the runtime to supply. Deploy the one fused .wasm through the normal content-addressed path. See Compose components into one handler.

boatramp validate

Parse and check a project.cfg (its routing section). Argument: [PATH] — the config to validate (default project.cfg). See the routing schema.

boatramp deployments

List a site’s deployment history.

boatramp rollback

Roll back to the previous (or a specific) deployment.

boatramp status

Show a site’s current deployment (id, age, size). No command-specific flags.

boatramp domain

Attach/detach hostnames to a site (virtualhost routing). See Attach a custom domain.

domain add flags:

boatramp alias

Manage named pointers (staging, previews) to deployments. See Publish, roll back & alias.

boatramp access

Configure visitor access control. See Restrict visitor access.

boatramp handlers

Manage a site’s handler policy — enable/disable, the import allowlist, resource caps, the edge response cache, and browser cookie auth. See Handler host bindings.

boatramp function

Manage top-level functions — deploy, roll back/alias, invoke, triggers, and the local dev harness. Takes a --server flag; site-scoped sub-actions also read --site.

boatramp graphql

Manage a project’s GraphQL admin — the persisted-operation safelist and the federation subgraph registry. See Serve a GraphQL API.

boatramp tenancy

Manage a project’s tenancy schema — the per-table tenant-key map that scopes guest sql/orm queries. Project·Admin. See Isolate tenants in one database.

boatramp secrets

Manage a project’s internal, sealed secret store (a guest names a secret as boatramp:<name> in its secrets map). The store holds only sealed bytes — the API never returns a value.

boatramp email

Manage a project’s SMTP delivery profiles (a guest’s email capability selects one by name). Needs the email feature. Passwords stay sealed — never returned. See Send email from a function.

boatramp sql

Operator SQL to a managed database. See Handler bindings.

boatramp token

Manage control-plane API tokens. See Bootstrap authentication and the RBAC reference.

create / mint flags:

attenuate flags:

boatramp cluster

Operate a self-hosted cluster’s dynamic-join membership. See Deploy a self-hosted cluster.

boatramp operator

Run the in-binary Kubernetes operator, or print its install manifests. See Run on Kubernetes. The operator feature is in the default (batteries-included) build; a minimal build re-adds it with --features operator.

boatramp security

Inspect the operator security posture. See Security posture.

boatramp auth

Generate/inspect the control-plane root key and edit the RBAC policy. See Authentication & authorization.

boatramp gateway

Publish a private service through the reverse-proxy gateway. See Expose a private service.

boatramp compute

Manage Firecracker microVM compute workloads. See Run a container or microVM.

set takes exactly one root-filesystem source (matched to the substrate); build instead takes --image + --size-mib and produces a --rootfs source:

The kernel blob

A microVM boots an uncompressed Linux kernel (vmlinux) plus an ext4 rootfs. --kernel accepts a local file, a URL, or the content-addressed blob hash of a kernel already uploaded; a file or URL is uploaded for you, and the server fetches the blob and boots it. Supply a Firecracker-compatible vmlinux (build one, or use a released microVM kernel) and provision it once, shared across workloads. See Run a container or microVM.

boatramp db

Read-only inspection of a project’s managed databases. A managed database is declared in the databases: block of an apply manifest — boatramp then provisions it, mints and seals its credential, and follows the workload across restarts. There is deliberately no db create: the manifest is the sole authoring surface (a create verb would compete as a second source of truth), so this group only reads what apply declared. The declaration and provisioning gate at Project·Admin; these read verbs are Project·Read. Takes the common --server flag.

--json (a global flag on the group) emits the raw record instead of the human table. To declare or change a database, edit the manifest’s databases: block — see Declare a managed database, Declare a project with apply, and the project.cfg schema.

boatramp blob

Upload artifacts and manage the node’s blob storage backend. blob put is the day-to-day artifact uploader; the migrate / drain / purge / status verbs move a node from one blob backend to another (fs→cloud, provider→provider, region→region) without a re-apply, then reclaim the old store.

The three blob-storage migrate/drain verbs. blob migrate is offline — it builds both backends in the CLI process from two node config files and never contacts a server, so it needs local access to the backends’ credentials (for a pre-boot copy, or a node you can shell into). blob drain is its daemon-mediated counterpart for a managed node reachable only over the control plane: the running daemon (which already holds both backends open) drains its own configured secondary. blob purge --drained-source then removes the decommissioned old store. See Switch the blob backend with zero downtime. (boatramp blob migrate is unrelated to the top-level boatramp migrate store re-key.)

blob migrate

Copy every object from a source blob backend to a destination backend, offline. It is a node-local operation: it builds both backends in-process from node config files (boatramp.cfg shape — each side’s [serve] blob block + optional [secrets] for a sealed S3 credential), so it takes no --server and needs local credential access, not a control-plane token. The copy get→puts each object, skipping any key already head-present in the destination at a matching size — so it is idempotent and resumable (a re-run after an interruption is a near-no-op) and read-only on the source (it never deletes, and the source stays authoritative until you flip [serve].blobs). The resolved source/dest identities are echoed and an equal source==dest is refused.

A verified fallback secondary → primary drain additionally prints SECONDARY FULLY DRAINED — safe to remove [serve].blob_fallback and restart the node.

blob drain

Drain the running daemon’s configured [serve.blob_fallback] secondary → primary over the control plane — for a managed node reachable only via --server (no local disk / no fly ssh), where the offline blob migrate cannot run. The client names no source or destination: the daemon (which already holds both backends of its fallback composite open) drains only its own configured pair, a tighter authorization surface than the offline CLI’s arbitrary --from/--to. Requires --server; gated at System·Admin (a project admin / publisher / deployer cannot reach it). No fallback configured ⇒ 422.

Progress streams as it arrives; on a verified drain it prints SECONDARY FULLY DRAINED — safe to remove [serve].blob_fallback. The copy is resumable, so a dropped connection (e.g. an edge idle-timeout on a long drain) is safe to re-run.

blob purge

Reclaim a provably-safe blob set over the control plane. Dry-run by default (reports what would be reclaimed and deletes nothing) — pass --apply to execute. Gated at System·Admin. Exactly one mode is required:

blob status

Print the node’s structured blob migration posture — whether a read-fallback secondary is currently attached (the node is mid-migration) — as { "blob_fallback_active": <bool> }. The direct answer to “is this node still in transition mode?”, instead of grepping the startup log warning. Read-only (System·Read).

boatramp config

Read and change the dynamic daemon config — operational knobs that converge fleet-wide without a restart. See the dynamic daemon config reference and the configuration model.

config set on a restart-class key (a trust anchor, posture, or listener setting) fails with a pointer to boatramp.cfg rather than silently doing nothing.

config migrate

config migrate <file> upgrades an apply manifest to the current schema and prints the result (or, with --write, rewrites the file in place). It is purely client-side — it reads and rewrites the file locally and never contacts a server.

The version: semantics drive it:

• Absent version: — the manifest is parsed strictly against the current schema. An old-shaped manifest that omits version: fails with an error pointing here.
• version: N older than current — the manifest opts into the loose-parse → migrate → typed pipeline: it is migrated forward through the registered chain (vN → … → current).
• The migrated output omits version: (current = absent). Declare version: <what you wrote against> only to keep migration support for a future schema change.

# Upgrade a pre-v0.6.0 manifest in place (add `version: 1` at its top first).
boatramp config migrate apply.cfg --write

See Declare a project with apply for the manifest schema and the version-migration workflow.

boatramp mcp

Run the Model Context Protocol server so an AI agent (Claude, Codex, …) can drive one or more instances. Bare boatramp mcp serves over stdio (what a desktop agent spawns); the server can also be reached over HTTP at /mcp on any boatramp serve (on by default). See Drive boatramp from an AI agent.

setup add flags: --token <spec> (an env:VAR / path:/file / literal token), --holder-key <spec> (a cnf holder key for DPoP), --server-pubkey <hex> (pin the server’s raw public key), --insecure (skip TLS verification). Secrets are stored as specs, never resolved into the file.

boatramp dns

Configure DNS and issue wildcard preview certificates. Needs the acme-dns feature. Every sub-action takes --provider <name>; each provider reads its credentials from the environment (see DNS providers).

boatramp logs

Tail a site’s — or a standalone function’s — captured guest stdout/stderr. See Observe a running server.

boatramp stats

Show a site’s handler invocation stats, consumer lag, and dead letters. No command-specific flags.

boatramp dlq

Purge or redrive a consumer topic’s dead-letter queue. See Run background work.

boatramp prune

Delete orphan deployments and unreferenced blobs. See Prune & scrub.

boatramp scrub

Verify every stored blob still hashes to its key (integrity scrub). No command-specific flags.

boatramp cert-status

Show cluster-managed certificate status (domain + expiry). No command-specific flags.

boatramp completions / man

boatramp cloudflare

Deploy boatramp to Cloudflare Containers natively over the CF REST API (no wrangler) — behind an edge Worker, as a single durable instance with all state in R2. Needs the cluster feature and CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN (Workers Scripts, Containers, R2, D1 scopes). A multi-node Raft quorum isn’t possible on the platform, so only --quorum 1 deploys. See Deploy on Cloudflare Containers.