DocsDeploy & operate

Command line

Every sluurp command, what it is for, and the options used most.

Everything is in one binary, sluurp. sluurp --help lists commands and sluurp <command> --help lists a command’s options. To start a server for an app:

sluurp serve --public ./app

Every command takes --dir <DIR>, the data folder (one SQLite file per project). By default, it is sluurp_data in the current directory. sluurp -v (or --version) prints the version.

Features include:

  • A server, a compiler to one binary, and a test runner
  • Backups, restores, clones and migrations for the data
  • Bun itself, carried in the executable
  • Versions pushed, deployed, promoted and rolled back by channel
  • Plugins, swarms, encrypted secrets and licences

Serving

CommandWhat it does
serveStart the server: API, admin UI at /_/, and the --public app
compileBuild a single binary with one app embedded
testRun an app’s tests in a headless Chrome, Edge or Chromium, on a fresh database; --grep, --coverage (Testing)

serve options:

Option
--public DIRThe app at /: a folder or repository URL. NAME=DIR mounts another at /NAME/; repeatable
--addr HOST:PORTThe address to listen on; by default 127.0.0.1:8090 (this machine only)
--port PORTThe port alone, keeping the host: --port 3000
--host HOSTThe host alone, keeping the port: --host 0.0.0.0 to be reached from other machines
--no-hot-reloadWatch no files, for production
--admin-auto-loginSign the admin in as the first superuser without a password, from this machine only. For development; a warning is printed at start. Never use it on a server others can reach
--fetch-allow HOSTSHosts server code’s fetch may reach though they are on this machine or the private network, separated by commas: localhost, db.internal, or *.internal for every name under it. For every project; SLUURP_FETCH_ALLOW says the same. See the server library
--attach NAME=FILEUse an existing SQLite database in place (Existing SQLite databases)
--events [ADDR]Accept local events over UDP (Hooks and events)
--channel NAME, --appsServe a published bundle, or all registered apps by hostname, instead of a folder
sluurp serve --public ./app --public reports=./reports --addr 0.0.0.0:8090

When it’s ready, the server says so, and where to find everything:

  SLUURP v0.4.0  ready in 50 ms

  ➜ App:     http://localhost:8090/
  ➜ Admin:   http://localhost:8090/_/
  ➜ API:     http://localhost:8090/api/
  ➜ Network: use --addr 0.0.0.0:8090 to expose
  ➜ press h + enter to show help

On a terminal, a few keys work while it runs: o opens the app in the browser, a opens the admin, c clears the screen and q quits, each followed by Enter. While you develop, each file the page takes in is a line of its own (11:20:35 [sluurp] hmr update /routes/index.tsx). When the app is bundled for production, a table lists each file with its size and compressed size, marks the ones over 500 kB, and says how long it took.

Colour is used on a terminal only. Output to a file, a pipe or a service’s log is plain, and so is any output when NO_COLOR is set.

Environment
SLUURP_FILESWhere uploaded files go (Storage)
SLUURP_DISKWhere Sluurp.disk keeps each project’s folder
SLUURP_LOG_FILE, SLUURP_LOG_FORMATStructured logs (Logs)
SLUURP_FETCH_ALLOWAs --fetch-allow
SLUURP_S3_BUCKET and the restFiles in a bucket (Files)
NO_COLORPlain output

Data

CommandWhat it does
migrate APPRun an app’s migrations; --plan previews
schema plan, schema applyDiff a schema.json against the database, or apply it
import FILEImport collections and records from an import document
superuser EMAIL [PASSWORD]Create an administrator, or reset their password. Leave the password out and it is asked for twice in the terminal, shown as stars, so it stays out of your shell history
backupBack up every project to a dated folder: only what changed since the last backup is written, and each still restores whole. --offsite then copies every backup not yet offsite
backup list, backup verify [NAME]List the backups, or read them back and check every page; --offsite for the copies offsite
backup fetch NAMEBring an offsite backup back into snapshots/, to restore like any other
restore NAMEPut a backup back, with the server stopped: sluurp restore latest, or a backup’s name as the Backups screen shows it. What was there is backed up first. --from-offsite fetches it from offsite first, as on a new machine
squash FROM TOFold the backups from FROM up to TO into TO, as squashing commits does
clone DIRCopy this server’s data into another data directory, for a staging server on a copy of production: read-only here, not its swarm (--replace to refresh an earlier copy)
migrationsShow Sluurp’s internal migrations applied to a project
benchBenchmark collections on this machine (Why SQLite)

Packages

An app’s packages are Bun’s: bun add, bun install. Components come from shadcn’s registries: bunx shadcn add button @sluurp/date-picker (Components).

CommandWhat it does
bun ARGSBun itself, as the executable carries it: sluurp bun add zod, sluurp bunx shadcn add dialog
cacheShow where production bundles are kept; clear empties them

Publishing

CommandWhat it does
push DIRSave the app as a new version (a bundle); --deploy CHANNEL also deploys it
bundlesList the saved versions, and which one each channel serves
deploy CHANNEL BUNDLEServe a saved version on a channel, after a snapshot of the data
promote FROM TOServe on one channel exactly what another serves: staging’s version on production
rollback CHANNELPut a channel back on the version it served before (the code; data stays as migrations left it)

To release, push the app, deploy it to staging, try it there, promote staging to production, and roll production back if something is wrong. A server serves one channel with serve --channel production, or each app on its own hostname with serve --apps and sluurp app add NAME --host … --channel …, and switches to whatever its channel points at without a restart.

sluurp push ./app --label v1.4 --deploy staging
sluurp promote staging production
sluurp rollback production

To publish on every push instead, connect a git repository with sluurp app add. app list shows the connected repositories, app sync NAME deploys the current commit, app seed NAME applies the bundle’s seeds/ files, and app remove NAME disconnects one (its bundles are kept).

Plugins and swarms

CommandWhat it does
plugin add/remove/update/listInstall and manage plugins from a registry or a folder; plugin new and plugin release for your own
cluster init, cluster status, cluster tokenStart a swarm, see its nodes, and get a token for serve --join

Configuration and security

CommandWhat it does
env encrypt, env enc, env dec, env rotateEncrypt secrets in .env files with the master key, and rotate it (Environments and secrets)
outboundList and change what server code may fetch (Security)
licenseActivate a business licence with license request KEY; license show says what this server is licensed for
license keygen, import-key FILE, import-ledger FILEFor running your own licence server with the Licences plugin: make its signing key, or bring in one you kept, and move in a ledger of licences already issued. The key is kept encrypted in the environment as LICENSES_SIGNING_KEY; --env picks the environment (production by default)

Other

CommandWhat it does
emit NAME [JSON]Send an event to a server running with --events
i18nList unused keys in an app’s i18n.json; --prune removes them
types DIRWrite the editor types an app gets (.sluurp/ and a tsconfig to extend) into a folder that isn’t served, such as a plugins repository
tailwind FILESPrint the stylesheet the server would serve for the classes in these files; --css adds an app stylesheet

View as Markdown