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. Sample data (unless blank or --no-seed) — POST /sample-data/install. A local dev deployment that already has OWLAT_DEV_MODE=true gets the fuller /seed/demo dataset instead (dummy teammate sign-ins + Postbox mailboxes); no install flow ever turns that flag on.
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"

sample-data

The demo dataset a real install can actually use. install POSTs to /sample-data/install, remove to /sample-data/remove, status to /sample-data/status — all three authenticated with the X-Instance-Secret header (the on-box operator secret from .env, the same one /seed/admin uses) and not gated on OWLAT_DEV_MODE. That distinction is deliberate: turning dev mode on to reach /seed/demo would also unlock the full-wipe /dev/reset endpoint and drop BetterAuth's rate limiting on a production instance.

owlat sample-data install   # idempotent — re-running inserts nothing new
owlat sample-data status    # how many sample rows are left
owlat sample-data remove    # deletes exactly those rows (prompts unless --assume-yes)

What it writes: 15 contacts across 3 topics, email templates and saved blocks, a sent campaign with per-recipient stats, an automation, a webhook, transactional-email history, and a verified demo.localhost sending domain. What it does not write: user accounts or mailboxes. The dev-only /seed/demo seeds dummy teammate sign-ins whose password hashes are published in the repo's fixtures — those have no business on an instance anyone else can reach, so the sample-data selection leaves out the accounts and mailboxes loaders (apps/api/convex/seedDemo/pipeline.ts → SAMPLE_DATA_MODULES). It also leaves out the Gmail bulk-sender volume rollups, which on a real install would read as a genuine domain sitting just under the threshold in the compliance view.

The dataset is inert by construction. /seed/demo writes its automation active and its webhook enabled; the sample-data path runs the same loaders with { inert: true }, which writes the automation paused (no activatedAt) and the webhook disabled. That matters because neither subscription is seed-aware at fire time: the automation triggers on contact_created and the webhook pool picks up every active subscription, so a live sample row would mail your next real signup a demo promo and POST that person's details to a fixture URL. Turn either on yourself if you want to watch them run.

Removal is exact rather than a table wipe: every row a loader inserts carries seedTag: 'demo', removal deletes only tagged rows, and it re-checks the tag inside the delete transaction. A sample contact you edited is still tagged and still goes; a contact you created is untagged and stays. Deleting a sample contact or topic runs the same cascade a permanent contact delete does, so rows of your own hanging off one (an activity, an automation run, a membership) go with it instead of dangling. Because the tag has no index, removal scans page by page from an action rather than in one mutation, so it stays inside the per-transaction read limit on an instance that has since accumulated real data; if a table is large enough that the scan hits its page cap, the response carries truncated: true and the CLI says so — re-run to continue.

quickstart runs the same install step when you pick "explore with sample data", so a fresh install never needs OWLAT_DEV_MODE to look populated.

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-...

env --show instead lists the variables your current feature-flag state requires — the same required-vars set doctor checks, minus the docker / container probing. Each row shows whether the variable is set (*_KEY / *_SECRET / *_PASSWORD values masked) and which flag (or the provider-conditional send path) requires it, so you can see at a glance what is still missing before deploying.

owlat env --show

  KEY                           SET / VALUE      REQUIRED BY
────────────────────────────────────────────────────────────
✗ GOOGLE_SAFE_BROWSING_API_KEY  (unset)          scan.urls
✓ LLM_PROVIDER                  openrouter       ai
✓ MTA_API_KEY                   ********…        send path (EMAIL_PROVIDER=mta)

It is read-only and always exits 0 — use doctor when you want a pass/fail gate.

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. It also mints a one-time setup token, writes it to the root-owned .env (OWLAT_SETUP_TOKEN), and prints it to the console — copy it into the wizard's final step. The /api/setup/* endpoints run unauthenticated (there is no admin yet), so they require this token in an X-Setup-Token header, verified with a constant-time compare; a missing or wrong token returns 401. Without it, the first caller to reach the wizard could create the platform-admin account and rewrite .env. 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_* / SMTP_RELAY_*, 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. The provider step is an honest instance-level choice — run your own MTA, Amazon SES, or an SMTP relay (with Mailgun/Postmark/SendGrid/Brevo presets, or a custom server), plus Resend — and it validates the credential before continuing (a live API check for Resend, a real SMTP handshake + AUTH for a relay).
• Terminal wizard (--terminal) — a full TUI covering the same questions: deployment mode, feature picker, sending provider (own MTA / Amazon SES / SMTP relay / Resend), 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, and nothing in the install flow turns it on — demo content for a real install goes through sample-data, which is instance-secret authenticated and not dev-gated. /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