Docs / Serverless Objects / CLI reference

CLI reference

Every sobjects command and option, the sobjects.toml settings for celld and the native engine, and the environment variables the CLI reads.

The npm package serverless-objects installs one binary, sobjects. Every command takes --help. For dev and deploy, --help shows celld's own options.

Commands

Command What it does
sobjects dev [project] [celld dev options] Runs a project locally with celld. It doesn't run the ingress. With --engine native, it runs the app in Node instead.
sobjects deploy [project] [celld deploy options] Preflights the Wrangler config, bundles the app and uploads it to the bucket. Running nodes pick up the new version on their next poll.
sobjects build [project] [--strict] Bundles the app and checks every Node.js built-in it imports against Cloudflare's nodejs_compat support. Reports the app as portable or native-only.
sobjects up [--config PATH] [--detach] Starts the engine plus the configured ingress and admin API, in the foreground or in the background.
sobjects status Shows the status of a node started with --detach.
sobjects logs [--supervisor] [--tail N] Shows recent detached engine or supervisor logs.
sobjects down Stops a detached node and its supervisor. Waits for the engine to drain and release its lease.
sobjects supervise [--config PATH] Runs only the ingress and admin API in the foreground, next to a celld started separately.
sobjects dashboard [--config PATH] Prints the admin dashboard URL, which carries the admin token.
sobjects upgrade [--engine-version V | --rollback | --status] Installs and selects a pinned celld release.
sobjects service print|install [options] Generates a systemd or launchd unit for up.
sobjects --help, -h Help.
sobjects --version, -v Installed version.

Command options

up, supervise, dashboard

Option Meaning
--config PATH The sobjects.toml to read. Default: $SOBJECTS_CONFIG, else ./sobjects.toml.
--detach, -d up only. Run the node in the background. Detached mode records process and log metadata; it is not an OS service manager.

supervise reloads TLS certificates from disk on SIGHUP.

logs

Option Meaning
--supervisor Show the supervisor's log instead of the engine's.
--tail N, -n N Number of lines, from 1 to 10000.

deploy

Option Meaning
--no-inspector Deploy the app without the storage inspection hook the dashboard uses.
celld deploy options Passed through to celld. --bucket, --endpoint and --region are filled from sobjects.toml when missing; explicit flags and the CELLD_BUCKET, S3_ENDPOINT and AWS_REGION environment variables take precedence.

build

Option Meaning
--strict Exit with status 1 if the app is native-only.

build lists each Node.js built-in the app imports, with the files that import it, and marks it as supported on Cloudflare, a non-functional stub there, or blocked by a missing nodejs_compat flag or compatibility date. It also flags packages that ship compiled native addons.

upgrade

Option Meaning
(none) Install and select the version this CLI pins.
--engine-version V Install and select a specific pinned version.
--rollback Select the previously selected version.
--status List versions.

Every installable celld version is pinned with a SHA-256 for each release asset: currently 0.6.2 (the default) and 0.6.1. A failed download or checksum leaves the current selection in place. Running nodes keep their version until restarted.

service

Option Meaning
--config PATH sobjects.toml to run. Default: ./sobjects.toml.
--kind KIND systemd or launchd. Default: launchd on macOS, else systemd.
--system systemd only: a system unit with CAP_NET_BIND_SERVICE.
--user NAME Account for a --system unit. Required with --system.
--force install only: replace an existing unit file.

See running as a service for where units are written.

dev --engine native

Option Default Meaning
--port PORT 8787 Listen port.
--host HOST 127.0.0.1 Listen address.
--persist-to DIR <project>/.sobjects/native Directory for object SQLite files.
--idle-evict-seconds N 60 Evict idle objects; 0 never evicts.
--backup-bucket s3://BUCKET/PREFIX none Back objects up to an S3-compatible bucket.
--backup-mode interval|durable interval durable holds each event's result until its writes are in the bucket.
--backup-interval-seconds N 10 Upload delay after a change, in interval mode.
--backup-retention-days N 7 Point-in-time recovery window in durable mode, 0 to 365.
--threads N 0 Run objects on N worker threads, up to 256.
--thread-stall-seconds N 30 Replace a thread that doesn't answer for this long.
--thread-memory-mb N none Replace a thread that exceeds this memory, 16 or more.
--node-name NAME none Join several nodes on one bucket prefix. Needs --backup-mode durable; can't be combined with --threads.
--lease-seconds N 10 Node lease length, 3 or more.
--peer-listen HOST:PORT none Peer listener for forwarded calls. Needs --node-name and SOBJECTS_CLUSTER_SECRET.
--peer-advertise URL listen address Address advertised to other nodes.
--drain-seconds N 30 How long shutdown waits for requests in progress, 0 to 600.
--trust-forwarded-headers off Take request.url's scheme and host from X-Forwarded-Proto and X-Forwarded-Host. Use only behind the sobjects ingress.

Details are on native engine and benchmarks.

sobjects.toml

Unknown keys are rejected, so a typo fails instead of being ignored. A file has either a [celld] or a [native] table, not both. Relative paths resolve from the config file's directory. Credentials never go in this file. The full annotated example is sobjects.example.toml.

[celld]
bucket = "s3://my-bucket/prefix"      # required: s3://, gs:// or az://
endpoint = "https://..."              # S3-compatible endpoint (or S3_ENDPOINT)
region = "auto"                       # or AWS_REGION
listen = "127.0.0.1:8080"             # keep on loopback behind the ingress
# internal_listen = "127.0.0.1:8081"  # celld operator API, loopback only

[ingress]
listen = "0.0.0.0:443"
redirect_http = "0.0.0.0:80"          # HTTP to HTTPS redirect; also serves ACME challenges
access_log = "-"                      # "-" for stdout; default is the state directory

[ingress.tls]                         # static certificates...
cert = "/etc/serverless-objects/tls/fullchain.pem"
key = "/etc/serverless-objects/tls/privkey.pem"

# [ingress.acme]                      # ...or ACME HTTP-01, not both
# email = "ops@example.com"
# agree_to_terms = true
# directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"

[[ingress.routes]]
hostname = "agents.example.com"       # exact, *.wildcard or *
# upstream = "http://127.0.0.1:8080"  # defaults to [celld].listen
# tls = { cert = "...", key = "..." } # per-route certificate, chosen by SNI

[admin]
listen = "127.0.0.1:8790"             # loopback-only dashboard and API

[celld]

Key Meaning
bucket Required. Bucket URI: s3://, gs:// or az://.
endpoint S3-compatible endpoint.
region Bucket region.
listen celld listener. Default 127.0.0.1:8080.
internal_listen celld operator API, loopback only. Enabling [admin] pins it (default: the [celld] port plus one).

[native]

sobjects up runs the native engine when the file has [native] in place of [celld]. Each key matches a sobjects dev --engine native flag.

Key Flag
project The Wrangler project to run, relative to the config file. Required.
listen --host and --port. Default 127.0.0.1:8787.
data_dir --persist-to. Default $SOBJECTS_DATA_DIR/native.
idle_evict_seconds --idle-evict-seconds
threads --threads
thread_stall_seconds --thread-stall-seconds
thread_memory_mb --thread-memory-mb
drain_seconds --drain-seconds
[native.backup] bucket, mode, interval_seconds, retention_days, endpoint, region Backup flags. mode defaults to durable here.
[native.cluster] node_name, lease_seconds, peer_listen, peer_advertise Cluster flags. Needs [native.backup] with mode = "durable".

[admin] is not available with [native] yet.

[ingress] and [admin]

See running as a service for ingress routes, certificate modes and the admin API.

Environment variables

Variable Purpose
SOBJECTS_STATE_DIR Detached PIDs, logs, ACME state and the admin token. Default $XDG_STATE_HOME/serverless-objects or ~/.local/state/serverless-objects.
SOBJECTS_DATA_DIR Engine installs and the inspector token. Default $XDG_DATA_HOME/serverless-objects or ~/.local/share/serverless-objects.
SOBJECTS_CELLD_BIN Use this celld binary instead of the pinned download.
SOBJECTS_CONFIG Default sobjects.toml for up and supervise, and for deploy when the project has none.
CELLD_SHUTDOWN_TOTAL_MS celld's graceful-shutdown bound; down waits slightly longer.
SOBJECTS_CLUSTER_SECRET Native engine: shared secret for signing peer requests, 32 or more characters, identical on every node.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN Bucket credentials.
S3_ENDPOINT, AWS_REGION Bucket endpoint and region, when not set in sobjects.toml.