Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command line

nanobom [--database-url …] [--log-format …] [--log-level …] <command> [options]

Every option is also an environment variable; the options every command reads, and those of serve, are in the configuration reference. nanobom --version prints the version, and nanobom <command> --help lists a command’s options with their defaults.

In the container image, run commands with docker exec <container> /app/nanobom … (or docker compose exec nanobom /app/nanobom …), which inherits the server’s NANOBOM_DATABASE_URL. Elsewhere, run them with the same NANOBOM_DATABASE_URL as the server.

Command
nanobom serveApply pending migrations, then serve the web interface and the API.
nanobom migrateApply pending database migrations and exit.
nanobom backup <destination>Write a consistent copy of the live database to a new file.
nanobom create-administratorCreate a local instance administrator.
nanobom token create, list, revokeManage API tokens.
nanobom project create, tokenCreate projects and print their upload token.
nanobom healthcheckCheck that the running server is healthy.

create-administrator, token and project apply pending migrations first, so they work on a new database; backup copies the database as it is.

nanobom serve

Serves the web interface, the upload API, /healthz and /metrics, and runs the schedule. Database migrations run at startup, before it accepts requests. On SIGTERM, requests in progress finish; a run in progress is not resumed and stays listed as running. Options: see Configuration.

nanobom migrate

Applies pending database migrations and exits, for a deployment that wants them as a separate step. Migrations only go forward.

nanobom backup

ArgumentVariable
<destination>NANOBOM_BACKUP_DESTINATIONThe file to write; it must not exist yet.

Writes a consistent copy of the live SQLite database with SQLite’s VACUUM INTO, without stopping the server or blocking it. It never overwrites a file; the directory must exist and be writable by the user nanobom runs as.

On PostgreSQL it writes nothing and fails with nanobom backup copies SQLite databases only; back up this Postgres database with its own tools, pg_dump for PostgreSQL: see Back up and restore PostgreSQL.

nanobom create-administrator

FlagVariable
--usernameNANOBOM_ADMINISTRATOR_USERNAMERequired.
--emailNANOBOM_ADMINISTRATOR_EMAILOptional; can then be used to sign in instead of the username.
--passwordNANOBOM_ADMINISTRATOR_PASSWORDRead from standard input when unset, as a plain line, shown as it is typed.
--personal-organizationsNANOBOM_PERSONAL_ORGANIZATIONSGive the user a personal organization (default true).
--password-minimum-lengthNANOBOM_PASSWORD_MINIMUM_LENGTHMinimum password length (default 12).

Creates a local account that is an instance administrator, typically the first one.

nanobom token

Manages API tokens with direct access to the database, like Settings → API tokens.

CommandFlags
nanobom token create--organization (NANOBOM_TOKEN_ORGANIZATION), --name (NANOBOM_TOKEN_NAME), --project (NANOBOM_TOKEN_PROJECT, optional), --scope (NANOBOM_TOKEN_SCOPE, upload or read, default upload)Create a token and print it. Without --project, the token covers the organization and, with the upload scope, may create projects. A read token only reads (scopes).
nanobom token list--organization (NANOBOM_TOKEN_ORGANIZATION)List an organization’s tokens.
nanobom token revoke--idRevoke a token, by the identifier token list prints. A project’s upload token cannot be revoked: renew it with nanobom project token --renew.
nanobom token create --organization acme --name "web CI" --project web
nanobom token create --organization acme --name Grafana --scope read
nanobom token list --organization acme
# 8	nanobom_91d0e2	Grafana	(organization)	never used	active	read
# 7	nanobom_3f9a1c	web CI	web	2026-11-08T03:12:44+00:00	active	upload
# 6	nanobom_c04e7b	Project token	web	2026-11-08T03:10:02+00:00	active	upload
nanobom token revoke --id 7

token create prints the token alone on standard output, so a script can capture it: TOKEN=$(nanobom token create --organization acme --name CI). It cannot be shown again.

token list prints one tab-separated line per token, revoked ones included: identifier, first characters, name, project (or (organization)), last use, state, scope. The scope comes last, so scripts written for earlier versions keep their columns. Each project’s own upload token is named Project token.

nanobom project

Creates projects and prints their upload token, with direct access to the database.

CommandFlags
nanobom project create--organization, --project, --name (optional, the slug by default)Create an empty project and print its upload token. A taken slug fails with the project "…" already exists.
nanobom project token--organization, --project, --renewPrint the project’s upload token. With --renew, replace it first: the old value stops working at once.
TOKEN=$(nanobom project create --organization acme --project web --name "Web shop")
TOKEN=$(nanobom project token --organization acme --project web --renew)

Both print the token alone on standard output, like token create.

nanobom healthcheck

FlagVariableDefault
--listen-addressNANOBOM_LISTEN_ADDRESS0.0.0.0:8080The server’s listen address; its health endpoint is reached over loopback when it listens on every interface.
--urlNANOBOM_HEALTHCHECK_URLHealth endpoint to check instead of the one derived from the listen address.
--timeout-seconds5Seconds to wait for an answer.

Exits successfully when the running server answers its health endpoint, /healthz, with 200. It is the container image’s health check, which has no shell or curl. It does not open the database.