CLI reference

The nimbus binary is the entire product surface: server, dev loop, deploy client, codegen, and operator tooling ship as one executable. Every command requires an explicit subcommand — there is no default action.

nimbus <command> [subcommand] [flags]

For what each surface currently supports, see Current capabilities.

nimbus start

nimbus start [flags]

Starts a Nimbus server in the foreground. Binds loopback by default; pass --allow-network (after rotating the local admin token) to bind a non-loopback interface. With --app-dir it runs one codegen preflight and serves that app; without it, the server starts empty and waits for deploys through the admin API. See Self-host for the deployment walkthrough.

Most-used flags:

The protocol adapters — Firestore and Cloudflare routes on the main listener, plus the MongoDB, DynamoDB, and S3 wire listeners on 27017, 8000, and 9000 — are served by default; a busy conventional port skips that listener with a warning. --no-firestore, --no-cloudflare, --no-mongodb, --no-dynamodb, and --no-s3 switch a surface off, --mongodb-port / --dynamodb-port / --s3-port pin an explicit port (busy is then a hard error), and credentials come from the generated wire-credentials.json in the data directory unless overridden — --mongodb-username with the env-only NIMBUS_MONGODB_PASSWORD, repeatable --dynamodb-access-key KEY_ID:SECRET:TENANT or NIMBUS_DYNAMODB_ACCESS_KEYS, and repeatable --s3-access-key KEY_ID:SECRET:TENANT or NIMBUS_S3_ACCESS_KEYS.

nimbus start accepts further flag families — TLS termination (--tls-cert + --tls-key), app loading (--app-dir, --skip-codegen, --debug-node-apis), Compose services (--compose-file), systemd socket activation (--systemd-socket-activation), licensing (--license-file, falling back to NIMBUS_LICENSE_FILE then ~/.config/nimbus/license.json), per-provider storage settings (--libsql-*, --postgres-*, --mysql-*), runtime limits (--runtime-heap-mb, --runtime-timeout-secs, and the other --runtime-* flags), and at-rest encryption (--encryption-key-provider and the other --encryption-* flags). The full flag ↔ environment variable ↔ config-key cross-reference lives in Configuration.

nimbus dev

nimbus dev [flags]

Starts a local development server with dev defaults: watched codegen reruns, local generation activation, an auto-created tenant (demo, or the discovered Firebase project id for Firestore client apps), and automatic browser launch of the operator console. When --app-dir is omitted, the app directory is auto-detected by walking up from the current directory to the nearest .git boundary. See Quickstart.

Adapter detection is automatic. nimbus dev reads the app's package.json and sources to pick the adapter (Convex, Cloud Functions, or the Firestore client wiring), writes Nimbus-owned NIMBUS_* keys to the app's .env.local when it detects the mongodb or @aws-sdk/client-dynamodb driver, and re-runs detection live when package.json changes — an adapter added mid-session is adopted without a restart. The server keeps serving even when no adapter is detected.

Browser auto-open is also suppressed automatically in non-interactive environments ($CI or $NO_BROWSER set, or stdout is not a TTY).

Use --no-compose-discovery when the dev session must not load a Compose project from its current directory or parent directories. Explicit --compose-file behavior and default discovery stay unchanged when the flag is absent.

nimbus deploy

nimbus deploy [TARGET] [flags]

Packages generated app artifacts and pushes them to a self-hosted Nimbus instance, printing a diff of functions, HTTP routes, schema, and runtime-bundle changes. The target resolves from the positional TARGET (a URL or a configured target name) first, then the NIMBUS_TARGET / NIMBUS_TARGET_URL environment variables, and defaults to the running local server when omitted; the token resolves from --token, then NIMBUS_DEPLOY_TOKEN, then tokens stored by nimbus auth login. The deploy route also requires the server's local admin token: when the target URL is a loopback address on the same machine, nimbus deploy reads it from the local token file automatically; for a remote server, pass --admin-token or set NIMBUS_ADMIN_TOKEN. The server-side contract is documented in Deploy & admin API.

nimbus run

nimbus run [TARGET] functions <selector> [jsonArgs] [flags]

Invokes a Nimbus function on a selected target. TARGET is one optional positional: a URL (http/https), a configured target name (see nimbus target), or omitted to discover the running local server. NIMBUS_TARGET and NIMBUS_TARGET_URL are accepted as env fallbacks.

Most-used flags:

nimbus run exec -- <argv...> is parsed as reserved vocabulary, but raw command execution is not shipped yet. It resolves the target and then exits with an actionable error instead of bypassing the service/sandbox/node workload-control path.

nimbus target

nimbus target <subcommand>

Manages the named-target registry at ~/.config/nimbus/targets — the named endpoints that deploy, run, sandbox, and list resolve instead of a raw URL. Run nimbus target --help for the add, list, and remove subcommands.

nimbus explain

nimbus explain [flags]

Explains the effective Nimbus configuration and runtime admission decisions for a target — how flags, environment, and config-file values resolve. Run nimbus explain --help for its options.

nimbus validate

nimbus validate [flags]

Validates a Nimbus project's configuration or an operator policy file before you apply it, reporting problems without starting a server. Run nimbus validate --help for what it checks.

nimbus list

nimbus list <resource>

Lists Nimbus resources on a target, such as sandboxes and services. Run nimbus list --help for the resource kinds it enumerates.

nimbus sandbox

nimbus sandbox create [TARGET] --template NAME
nimbus sandbox list [TARGET]

Reserves the top-level sandbox resource namespace and target-resolution contract. TARGET is one optional positional — a URL or a configured target name; omitted resolves the running local server — exactly like nimbus run. The commands parse and resolve targets through the same TargetContext seam as nimbus run, then fail actionably until sandbox lifecycle execution is owned by the service/sandbox/node workload-control path.

nimbus codegen

nimbus codegen [--app <path>]

Generates _generated/* files and the runtime bundle from a nimbus/ or convex/ source root. Codegen is embedded in the binary — there is no separate npm codegen step. See Developers for the authoring workflow.

nimbus init

nimbus init <adapter> [directory] [flags]

Scaffolds a new Nimbus project. The adapter argument is required and selects the project template; existing files are never overwritten.

nimbus scaffolds functions in nimbus/ against the @nimbus/nimbus SDK. convex scaffolds functions in convex/ against the convex compatibility package. Both serve the same app through the same engine, so pick nimbus for a new project and convex to keep an existing Convex codebase portable.

nimbus kv

nimbus kv [flags]

Runs a loopback RESP (Redis) listener speaking RESP2 and RESP3 on 127.0.0.1:6380. Authentication is mandatory and the listener serves one tenant per credential; if no password is given (--password or NIMBUS_KV_PASSWORD), a dev credential is generated and printed at startup. The command surface and flags are documented in KV (Redis) compatibility.

nimbus object-storage

nimbus object-storage <subcommand>

Administers the object byte plane — the store the S3 adapter reads and writes through. Subcommands cover placement policy (set-placement), the encryption master key (bootstrap-master-key), garbage-collection and erasure health (gc-status, erasure-status, erasure-heal), offline byte-plane backup and restore (backup-object-store, restore-object-store), and destructive per-tenant removal (tenant rm). The maintenance verbs are offline and fail closed while a server is running. Commands that open tenant metadata accept --control-data-dir <dir> for split-root deployments. See Object storage for the operator runbook.

nimbus token

Local admin token management.

nimbus token rotate

nimbus token rotate

Rotates the local admin token used for localhost server access. When a live server is discoverable, rotation goes through the running server; otherwise it rotates the on-disk token file offline. Takes no flags.

nimbus backup

nimbus backup create --data-dir ./data --out <file>
nimbus backup restore --in <file> --data-dir ./data

Offline whole-deployment backup and restore for the embedded providers (--provider sqlite|redb): one point-in-time archive per tenant in a single file, fingerprint-verified on restore. Run with the server stopped; restore requires a fresh data directory. Pass --control-data-dir <dir> on each command when the deployment keeps its control plane outside --data-dir. See Backup & restore for procedures, encrypted deployments, and external backends.

nimbus auth

Sign-in URLs for the local console and credentials for remote deploys.

nimbus auth url

nimbus auth url [--copy] [--open]

Mints a single-use launch URL for the local operator console. Requires a running server (nimbus start or nimbus dev).

nimbus auth token

nimbus auth token [--copy]

Prints the local admin token from the on-disk token file.

nimbus auth login

nimbus auth login --url <daemon-url> [--bearer <token>]

Stores a deploy bearer token for a remote Nimbus daemon in the local credentials file. nimbus deploy falls back to this store when NIMBUS_DEPLOY_TOKEN is unset.

nimbus auth status

nimbus auth status

Lists configured deploy connections with masked bearers and metadata. Takes no flags.

nimbus auth logout

nimbus auth logout --url <daemon-url>

Removes a stored deploy bearer.

nimbus auth rotate-admin

nimbus auth rotate-admin

Rotates the local admin token offline. Required before nimbus start --allow-network when the token has gone stale. A running daemon keeps its in-memory token until restart. Takes no flags.

nimbus ui

nimbus ui

Discovers the running local daemon and opens the operator console in a browser. It does not spawn a daemon — start one with nimbus start or nimbus dev first. Takes no flags.

nimbus machine

Manages local developer machines — the Linux guest VM that backs container workloads on macOS. Most subcommands take an optional machine [name] positional that defaults to default.

nimbus machine init

nimbus machine init [flags] [name]

Initializes a new machine: writes its config and state records and records the guest resource contract.

nimbus machine start

nimbus machine start [flags] [name]

Starts a machine, creating it first when it does not exist. Accepts the same creation flags as machine init (--cpus, --memory, --disk-size, --image, --identity, --ignition-path, --firmware, --volume), which apply only when start creates the machine, plus:

nimbus machine stop

nimbus machine stop [name]

Stops a running machine and persists the stopped state. No flags beyond the optional name.

nimbus machine status

nimbus machine status [flags] [name]

Displays machine status.

nimbus machine list

nimbus machine list [flags]

Lists initialized machines (alias: nimbus machine ls). The default machine is marked with * in table output.

nimbus machine info

nimbus machine info [-f <format>]

Displays machine host info: roots, cache locations, and the current machine release.

nimbus machine inspect

nimbus machine inspect [-f <format>] [name]

Prints the persisted machine record (config plus refreshed state).

nimbus machine set

nimbus machine set [flags] [name]

Updates a stopped machine's recorded resources; the next machine start applies them.

nimbus machine cp

nimbus machine cp [-q] <src-path> <dest-path>

Securely copies files between the host and a machine. Guest endpoints use NAME:/path notation (e.g. default:/tmp/file).

nimbus machine ssh

nimbus machine ssh [name] [command...]

Logs in to a machine using SSH, optionally running a command. If the first argument names an initialized machine it is treated as the machine name; otherwise all arguments are passed through as the guest command on the default machine.

nimbus machine rm

nimbus machine rm [name]

Removes an existing machine's config, state, and runtime layout when it is not running. No flags beyond the optional name.

nimbus machine os

Manages machine OS images.

nimbus machine os apply <image> [--restart]
nimbus machine os upgrade [--dry-run] [--restart]
nimbus machine os rollback [--restart]

upgrade switches to the supported machine OS image for the current nimbus release; rollback queues the previous bootc deployment for the next boot.

nimbus node

Manages Nimbus node service-manager installation artifacts (systemd units and Podman Quadlet files) on Linux hosts. The artifact subcommands select a target with --systemd (native unit) or --container (Quadlet), and a scope with --user or --system (default: system). node install requires an explicit target; the other artifact subcommands default to --systemd. See Run Nimbus as a service and Deploy on Linux.

nimbus node install

nimbus node install --systemd|--container [flags]

nimbus node status

nimbus node status [--systemd|--container] [--user|--system]

Shows the Nimbus node service status through systemd. Target and scope flags only.

nimbus node logs

nimbus node logs [--systemd|--container] [--user|--system] [--follow]

Prints Nimbus node service logs through journalctl.

nimbus node doctor

nimbus node doctor [--systemd|--container] [--user|--system]

Diagnoses host support for the selected node service mode. Target and scope flags only.

nimbus node uninstall

nimbus node uninstall [--systemd|--container] [--user|--system] [--dry-run]

Removes Nimbus node service-manager artifacts.

nimbus compose

Compose-backed local service lifecycle commands. All subcommands share one discovery rule for --file: explicit repeated --file flags win; otherwise the COMPOSE_FILE environment variable provides an ordered list (separator overridable with COMPOSE_PATH_SEPARATOR); otherwise Nimbus discovers Compose files from the current directory and parents. Lifecycle subcommands default to a deterministic per-project tenant, overridable with --tenant.

nimbus compose config

nimbus compose config [--file <path>]... [--services]

Validates and prints the resolved service plan from a Compose file.

nimbus compose up

nimbus compose up [service] [--file <path>]... [--tenant <id>]

Starts one or more declared services for the current Compose project. When the service name is omitted, starts all declared services.

nimbus compose down

nimbus compose down [service] [--file <path>]... [--tenant <id>]

Stops one or more persisted services for the current Compose project. When the service name is omitted, stops all persisted services in the tenant. Same flags as compose up.

nimbus compose ps

nimbus compose ps [-f <format>] [-n] [--file <path>]... [--all-tenants]

Shows persisted sandbox state for the current Compose project.

nimbus compose inspect

nimbus compose inspect <service> [-f <format>] [--file <path>]... [--tenant <id>]

Shows persisted sandbox details for one service.

nimbus compose logs

nimbus compose logs <service> [--file <path>]... [--tenant <id>] [--follow]

Prints persisted service logs for one service.

nimbus compose top

nimbus compose top <service> [-f <format>] [-n] [--file <path>]... [--tenant <id>]

Shows the persisted PID snapshot for one service.

nimbus compose export quadlet

nimbus compose export quadlet [flags]

Renders Podman Quadlet artifacts from an admitted Compose plan for operator review.

nimbus policy

Validates and explains Nimbus operator policy files. See Manage tenants for the policy model.

nimbus policy validate --file nimbus.policy.yaml [-f text|json]
nimbus policy explain --file nimbus.policy.yaml [-f text|json]
nimbus policy prove --file nimbus.policy.yaml [-f text|json]
nimbus policy diff --from before.yaml --to after.yaml [-f text|json]

Flags for validate, explain, and prove:

Flags for diff:

nimbus encryption

Encryption admin commands for local at-rest encryption. These commands read the active key provider and persistence settings from the same environment variables and config file as nimbus start (NIMBUS_ENCRYPTION_KEY_PROVIDER and friends; see Configuration). Operational guidance lives in Encryption.

nimbus encryption status

nimbus encryption status [--format text|json]

Inspects encryption coverage and status.

nimbus encryption migrate

nimbus encryption migrate --source <path> --provider <family> [flags]

Migrates a plaintext database to encrypted.

nimbus encryption export

nimbus encryption export --source <path> --target <path> --provider <family> [--tenant-id <id>]

Exports an encrypted database to plaintext for recovery.

nimbus encryption rotate-kek

nimbus encryption rotate-kek --path <path> [flags]

Rotates key-encryption keys: rewraps manifests without rewriting data.

nimbus encryption rotate-dek

nimbus encryption rotate-dek --path <path> --provider <family> [flags]

Rotates data-encryption keys; provider-specific and may rewrite data.

nimbus packages

Installs the embedded Nimbus JS packages into an app's .nimbus/packages/ directory so file: package specifiers resolve offline.

nimbus packages install

nimbus packages install [target] [--app-dir <path>] [--no-node-install]

Stages the embedded packages, points the app's package.json dependency at the staged copy, and runs the Node dependency install so the app can import it right away. When the app has no package.json, or npm is not on PATH, the staging and wiring still happen and the command says what is left to run.

Installing over a registry dependency records the spec it replaces under a top-level "nimbus" key in the same package.json, which is what lets nimbus packages uninstall put the original back.

nimbus packages uninstall

nimbus packages uninstall <target> [--app-dir <path>]

Undoes install for one adapter: restores the recorded registry spec — or removes the dependency when Nimbus added it — and deletes .nimbus/packages/ once no dependency points into it. Run npm install afterwards to update node_modules.

Uninstalling also records the detach, so the automatic wiring that nimbus dev, nimbus codegen, and nimbus deploy perform does not silently restore it. nimbus packages install <target> clears that record and wires it again.

nimbus packages verify

nimbus packages verify [--app-dir <path>]

Verifies provisioned package bytes against the binary's embedded checksums.