Setup CLI & Installer

Owlat ships a single self-host toolchain: a one-liner installer (install.sh) that bootstraps a host, and the owlat-setup CLI (built from apps/setup-cli/) that does everything from config through a fully deployed, seeded instance. This page is the command reference for both. For the narrative deploy guide, start at Self-Hosting; this page documents the individual commands those guides invoke.

The one-liner installer

install.sh is served at https://get.owlat.app. On a fresh Linux VPS with Docker and Docker Compose v2 installed:

curl -fsSL https://get.owlat.app | bash

The script (install.sh) does four things, then hands off to the CLI:

Because the wizard runs inside the wolvesdotink/setup Docker image, the host needs only Docker and Compose — no Bun or Node.

Installer environment variables

Non-interactive examples:

# Accept all defaults
OWLAT_ASSUME_YES=1 curl -fsSL https://get.owlat.app | bash

# Drive from a config file (CI / Ansible)
OWLAT_CONFIG_FILE=/path/to/answers.env curl -fsSL https://get.owlat.app | bash

owlat quickstart — end-to-end deploy

quickstart (apps/setup-cli/src/commands/quickstart.ts) takes a fresh clone all the way to a running, admin-bootstrapped, optionally-seeded instance. Every step is idempotent, so re-running is safe.

owlat quickstart

The flow:

1. Sanity checks — confirms you are in the monorepo (a turbo.json exists at --owlat-dir) and that the Docker daemon is reachable.
2. Config — if .env or docker-compose.override.yml is missing, it runs the setup wizard first; otherwise it reuses the existing config.
3. Mode prompt — populated (admin + demo data, the default), blank (no admin, no data — to test the real /auth/register signup flow), or custom (decide per step).
4. docker compose up -d — brings up the self-host stack.
5. Wait for Convex — polls /version on the Convex cloud port (3210). The application HTTP routes only exist after functions deploy, so the cloud port is probed here.
6. Deploy the backend — see Pushing Convex runtime env vars. This mints the admin key, deploys functions, and pushes runtime env vars.
7. Wait for HTTP routes — polls /api/v1/health on the Convex site proxy (3211), where the freshly-deployed http.route handlers (/seed/*, /dev/*, tracking, webhooks) live.
8. Bootstrap admin (unless blank) — see Admin bootstrap.
9. Seed demo data (unless blank or --no-seed).
10. Summary — prints the web app URL (http://localhost:3000), the Convex URL, and the admin email.

Quickstart flags

# Fully scripted populated install
owlat quickstart -y --email admin@example.com --name "Admin" --password "a-strong-password"

Command reference

Run any command as owlat <command> (after the installer symlink) or bunx owlat-setup <command> from a clone. Pass --help for the full usage banner.

bootstrap-org

Creates the first admin user and the singleton organization by POSTing to /seed/admin (see Admin bootstrap). It hashes the password with BetterAuth's scrypt format client-side, so the backend stores a credential that matches a normal login. It is idempotent: a 409 (admin already exists) exits 0.

owlat bootstrap-org --email admin@example.com --name "Admin" --password "a-strong-password"

seed and reset

seed POSTs to /seed/demo; reset POSTs to /dev/reset. Both endpoints are fail-closed behind OWLAT_DEV_MODE (see the dev-mode note) and require the X-Instance-Secret header. seed --reset wipes seed-tagged rows before re-inserting. reset deletes all users, the org, and every seeded row, so the next visit to http://localhost:3000 redirects to /auth/register — use it only on throwaway instances.

owlat seed            # idempotent insert
owlat seed --reset    # wipe seed rows, then re-seed
owlat reset           # full wipe (prompts unless --assume-yes)

feature and pack

feature toggles one flag from the feature flags catalogue and regenerates docker-compose.override.yml; dependency cascades are applied and reported. pack toggles a whole grouping at once. The three packs are:

owlat feature ai on        # enable a single flag
owlat pack marketing on    # enable campaigns + automations + transactional

Both print the new active compose profiles and remind you to run owlat restart to apply.

env

Sets a single variable in .env. The key must be an uppercase shell-safe identifier; values for *_KEY, *_SECRET, and *_PASSWORD are masked in the output.

owlat env LLM_API_KEY sk-...

doctor

Runs a checklist against the install and exits non-zero on any failure:

1. .env exists and parses.
2. Every env var required by the active feature set is populated.
3. docker-compose.override.yml exists.
4. At least one compose service is running (docker compose ps).

owlat doctor

Wrapper lifecycle commands

The installed /usr/local/bin/owlat wrapper (scripts/owlat) also exposes day-2 ops commands that are pure docker compose ceremony — these are wrapper-only and have no owlat-setup equivalent:

The wrapper additionally provides backup, restore, backup-schedule, and upgrade for backups and in-app updates.

Pushing Convex runtime env vars (convex-deploy)

Convex functions read their configuration from the deployment, not from the compose .env. The compose .env only configures the container processes; it does not reach the Convex function sandbox. So a deploy has three host-side steps (apps/setup-cli/src/lib/convexDeploy.ts), all of which are pure docker compose calls:

docker compose --profile deploy run --rm convex-deploy

The list of keys that get pushed is CONVEX_RUNTIME_ENV_KEYS, defined in packages/shared/src/convexRuntimeEnv.ts and re-exported from apps/setup-cli/src/lib/convexDeploy.ts, kept in sync with the EnvKey union in apps/api/convex/lib/env.ts. It covers auth and instance secrets, site URLs, email/MTA defaults, provider keys (Resend, SES), the LLM configuration, vector store, analytics, and the inbound-channel webhook secrets. Compose-only vars (ports, image versions, NUXT_PUBLIC_*, REDIS_*) are deliberately excluded — they never belong in the deployment.

Setup wizard: web vs terminal

owlat setup (apps/setup-cli/src/commands/setup.ts) is the first-run config wizard. It writes .env and the compose override only — it does not deploy or create your admin. (config is the same wizard, re-opened for an existing install.)

There are two paths:

• Web wizard (default when a browser is available) — primes .env for setup mode and points you at http://localhost:3000/setup. For SSH installs without a local browser, use the terminal wizard (below) instead. On the final "Launch" step its /api/setup/apply endpoint creates the admin (POST /seed/admin) and pushes the function-runtime env vars (EMAIL_PROVIDER, RESEND_API_KEY / AWS_SES_*, and the rest of CONVEX_RUNTIME_ENV_KEYS) into the Convex deployment over the admin API — the HTTP equivalent of convex env set, since the read-only web container can't run the convex-deploy step. So the email-provider choice actually reaches the sending code, not just .env.
• Terminal wizard (--terminal) — a full TUI covering the same questions: deployment mode, feature picker, sending provider (Owlat MTA / Resend / Amazon SES), AI provider (OpenRouter / OpenAI / custom OpenAI-compatible), optional integrations (Google Safe Browsing, PostHog), the admin account, and — for the self-hosted MTA — your EHLO and bounce domains.

The wizard generates all required secrets automatically (see below), mirrors the resolved flag state to .owlat-flags.json (so doctor, feature, and pack share the same baseline), and finishes by telling you to run owlat quickstart to actually bring the stack up.

Generated secrets

ensureSecrets() (apps/setup-cli/src/lib/secrets.ts) fills in any missing secret while preserving operator edits:

CONVEX_ADMIN_KEY is intentionally not generated here — it must be minted by the running backend during the deploy step.

Admin bootstrap

bootstrap-org (and quickstart) create the first admin by POSTing to POST /seed/admin (apps/api/convex/seedAdmin.ts).

POST /seed/admin
X-Instance-Secret: <INSTANCE_SECRET>
Content-Type: application/json

{ "email": "admin@example.com", "name": "Admin", "passwordHash": "<scrypt-hash>" }

The handler:

• Requires a matching X-Instance-Secret header (timing-safe comparison against the deployment's INSTANCE_SECRET); a mismatch returns 401.
• Is one-shot: if any user already exists it returns 409.
• On success (201) creates the BetterAuth user, the credential account (storing the scrypt password hash), the singleton organization (slug derived from the email local part), an owner membership, the user profile, and the instance settings.

The CLI hashes the password before sending: bootstrap-org derives a BetterAuth-compatible scrypt hash (apps/setup-cli/src/lib/passwordHash.ts) so the seeded credential matches a normal login. You never send the plaintext password to the backend.

Dev-only endpoints

/seed/demo and /dev/reset are guarded by OWLAT_DEV_MODE (apps/api/convex/devShortcuts/_guard.ts) and are fail-closed: unless OWLAT_DEV_MODE is truthy in the Convex function runtime, they return 403. Local dev installs default it on; production self-host leaves it off. quickstart flips it on only when you ask it to seed demo data. /seed/admin itself is not dev-gated — it is the production admin-bootstrap path, protected by the instance secret and the one-shot check.

Related