@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