CLI reference
The server is one binary, cloudpdf-server, with a handful of subcommands. It’s
the entrypoint of the Docker image too, so
every command below works the same whether you run it from npm or a container.
# npm
cloudpdf-server <command> [args]
# Docker (the binary is the entrypoint)
docker run --rm ghcr.io/embedpdf/cloudpdf-server:latest <command> [args]Run cloudpdf-server --help to print the commands and the full CLOUDPDF_*
environment surface.
serve#
Starts the HTTP server. This is the default — cloudpdf-server with no
arguments runs serve.
cloudpdf-server serveReads its entire configuration from the environment — see the
configuration reference. Listens on PORT
(default 3000) and exposes /healthz, /readyz, /v1/docs/*, and
/v1/admin/*.
migrate#
Manage the database schema. See Migrations for the recommended flow per deployment.
| Command | What it does |
|---|---|
migrate status | Show applied, pending, and drift state. |
migrate up | Apply all pending migrations. |
migrate up --dry-run | List what would be applied, without changing the database. |
migrate validate | Exit non-zero if drift is detected. |
migrate validate --strict | Treat pending migrations as drift too. |
migrate down | Roll back migrations (manual break-glass; destructive). |
cloudpdf-server migrate status
cloudpdf-server migrate upRolling back#
migrate down is a deliberate, destructive break-glass tool. It requires
--yes because containers are non-interactive:
| Flag | Effect |
|---|---|
--to NNN | Roll back everything newer than version NNN. |
--steps N | Roll back the N highest applied (default 1). |
--all | Roll back every applied migration. |
--dry-run | Preview the plan without touching the database. |
--yes | Required to actually run. |
--force | Roll back even if the up-checksum drifted from the code. |
# Preview first
cloudpdf-server migrate down --steps 1 --dry-run
# Then commit to it
cloudpdf-server migrate down --steps 1 --yesmigrate down can drop data. Take a database backup first, and
prefer rolling forward with a corrective migration over rolling back in
production.
db doctor#
Connects to the database, runs validate, and prints version information. A fast
way to confirm credentials, connectivity, and schema health:
cloudpdf-server db doctoraudit export#
Exports a closed day’s audit_log rows to JSONL in the object store — useful for
shipping audit records to long-term storage or a SIEM:
cloudpdf-server audit export --day yesterdayquarantine#
Host-isolation deployments journal engine crashes and refuse documents that
repeatedly crash the engine (422 DocumentQuarantined). Inspect and release
them:
# What is quarantined right now, and why
cloudpdf-server quarantine list
# Release one document (audited, with a reason)
cloudpdf-server quarantine clear <base-sha> --reason "vendor fixed the file"A quarantine expires on its own after its TTL; clear is for releasing one
early after you’ve verified the document (or upgraded the engine).
Exit codes#
The commands use conventional exit codes (0 success, non-zero on failure),
which makes them safe to wire into CI, init containers, and Helm hooks. For
example, migrate validate failing non-zero is exactly what lets a deploy refuse
to proceed on a stale schema.