Connected apps with 3rd-party data hosts jsr.io/@civility
README.md

@civility/cli #

civ — the CLI for running and using Civility Cloud: self-hosting a server, operating it, account portability, and minting the identities apps use to talk to one.

Install #

deno install jsr:@civility/cli -Afg --name=civ --unstable-kv

Commands #

civ id #

Generate a new opaque appId (for apps built without civ init scaffolding). The id is printed to stdout on its own line so the command is pipeable; usage guidance goes to stderr.

civ id
civ id | pbcopy

Use it once in new CloudStore({ storage: { db: backend }, cloud: { appId } }) and never regenerate it — grants, tokens, and synced data all bind to this id.

civ static #

Transform and move static files from an input directory to the dist output. Images (jpg/jpeg/png/tiff) are resized and stripped with ImageMagick and a photos.json (dimensions + dominant color) is emitted; other files are copied as-is.

civ static
civ static -i static -o dist/static --max-size 1200 --quality 85
civ static --skip-resize   # copy only, no ImageMagick needed

civ init-config #

Create a default civility.json in the current directory.

civ init-config

civ api start #

Launch the Civility sync and admin server.

The server registers the standard AI, Podcast Index, and RSS-fetch services, but makes no service calls until an operator enables Allow service proxying in /admin/services. The switch is persisted and takes effect without restarting. The same panel manages host bundle credentials; users can instead supply their own provider credentials through their apps. Podcast Index requires a key and secret (user-owned or host-owned); RSS fetching needs no key. No command-line proxy flag is required. Each registered service can also be disabled or restricted to selected supported execution modes through that panel.

Use /admin/billing → Billing tiers to define plan IDs, labels, paid status, quota/retention presets, and per-user rate limits. Start with an unpaid free tier; paid plans also require provider price mappings. Tier catalogs persist and apply without restarting, with startup configuration as a resettable fallback.

Use /admin/maintenance for automatic-job switches, live UTC schedules, pause-all, recorded run results, and confirmed manual sweeps. Automatic dispatch requires a Deno cron-capable process (--unstable-cron); manual runs work without it. Startup scheduling flags remain resettable fallbacks. Operate one scheduler per database.

Use /admin/email → Advanced Resend options for a trusted API base URL, per-request timeout and transient retry count. Blank resets to transport defaults; zero retries disables retrying. Save before sending a test.

Use /admin/limits for server-wide quotas, upload caps, retention, bundle allowances, and rate limits. Changes persist and apply without restarting. --max-db-bytes and --max-blob-bytes remain startup fallbacks; saved admin settings take precedence. Blank fields or the reset button restore startup values.

First run — interactive setup wizard:

civ api start

Prompts for data storage (SQLite) and blob storage (local filesystem or S3), then saves the config to ~/.config/civility/api.json and starts the server. CIVILITY_AUTH_SECRET must be set in the environment (see civ api gen-secret).

Subsequent runs — loads saved config automatically:

civ api start

Override flags — skip the wizard, merge with saved config:

civ api start --port 9000
civ api start --db sqlite --blobs s3

Reset — re-run the wizard:

civ api start --reset

Adapter options #

Flag Values Default
--db sqlite (local file) sqlite
--blobs fs (local filesystem), s3 (S3-compatible) fs

Environment variables #

Secrets are never stored in the config file — pass them via env vars:

Variable Required for
S3_ENDPOINT --blobs s3
S3_BUCKET --blobs s3
S3_ACCESS_KEY --blobs s3
S3_SECRET_KEY --blobs s3
S3_REGION --blobs s3 (optional)
S3_CDN_URL_BASE --blobs s3 (optional)
CIVILITY_ADMIN_TOKEN Enables /admin panel (static token)
CIVILITY_ADMIN_EMAILS Enables /admin for these accounts' sessions
CIVILITY_AUTH_SECRET Required by civ api start (see gen-secret)

civ api gen-secret #

Print a fresh base64 32-byte secret for CIVILITY_AUTH_SECRET (the JWT signing secret the server needs for email verification, password reset, and MFA tokens).

export CIVILITY_AUTH_SECRET=$(civ api gen-secret)

civ api billing init #

One-shot provisioning of the hosted billing provider (Stripe). Creates the products, recurring prices, and webhook endpoint the server's /admin/billing page needs, then prints the tier→price map and webhook signing secret to paste in. Idempotent — re-runs never duplicate prices. Never writes to the server or its database. Reads the Stripe key from STRIPE_SECRET_KEY (preferred).

export STRIPE_SECRET_KEY=sk_…
civ api billing init \
  --webhook-url https://your-server/api/v1/billing/webhook \
  --price pro=900
civ api billing init --json   # machine-readable output

civ api export / civ api import / civ api move #

Account portability (§6) from the command line. These talk to a running server over HTTP rather than touching its database — moving between hosts means talking to two servers, and only a client sits outside both.

# Download everything one account holds, as a zip.
civ api export --host https://civility.cloud --email me@example.com

# Load it into an account on another server.
civ api import civility-export.zip --host https://my.server --email me@example.com

# Both, across two servers, in one command.
civ api move --from https://civility.cloud --to https://my.server \
  --email me@example.com

The download resumes: if the output file is already partly written, the command asks for the missing byte range and appends. A large export over a bad connection continues where it stopped, and because the archive already exists on the server, retrying costs none of the account's daily allowance.

export deletes the server-side archive once it is safely on disk (--keep opts out) — it is a second complete copy of the account, and there is no reason to leave it sitting there. --parts db skips file bytes when only the metadata is wanted; import --mode replace clears server state for the apps the archive contains first, and never for apps it doesn't.

move stops short of one step on purpose: publishing the forwarding ("moved-to") note on the old server, which is signed by your identity key. Every path that touches that key is client-side by design, so the command prints the dashboard links for it rather than learning to unwrap identity seeds. It also cannot complete an MFA challenge at sign-in — it says so and points at the dashboard.

civ api gc blobs --once #

Run a single blob garbage-collection sweep and exit: quarantine unreferenced blobs, delete quarantined blobs past the grace window, and reconcile orphaned storage objects. For self-hosts on bare Deno where Deno.cron is unavailable — schedule recurring runs externally (cron, systemd timer). Uses the saved civ api start config plus S3_* env vars.

The grace period uses explicit --grace-days → saved /admin/limits blobGcGraceDays → built-in seven-day default, reading the database on every sweep. Zero is honoured at either override level and allows deletion as soon as a quarantined blob is eligible. Invalid negative, fractional, or non-finite values are rejected before sweeping.

civ api gc blobs --once
civ api gc blobs --once --grace-days 7 --json