moul.dev

Comprehensive configuration reference for environment variables, runtime settings, and CLI subcommands.

moul can be configured via environment variables, .env files in the project root, or CLI flags.

Environment Variables

Variable	Required	Default	Description	Example
`MOUL_ENV`	Yes	`development`	Environment mode (`development` or `production`).	`production`
`MOUL_ADMIN_KEY`	Yes	—	Master administrative key for backend API access.	`super-secret-admin-key-9988`
`MOUL_JWT_SECRET`	Yes	—	Secret key used to sign and verify JWT authentication tokens.	`jwt-secret-key-production-3344`
`MOUL_PORT`	No	`8090`	TCP port the Echo HTTP server listens on.	`8090`
`MOUL_DB_PATH`	No	`moul-local.db`	Path to the SQLite database file.	`/var/lib/moul/moul.db`
`MOUL_PUBLIC_URL`	No	`http://localhost:8090`	Canonical public URL used in transactional email links.	`https://api.myapp.com`
`MOUL_APP_NAME`	No	`moul-dev`	Custom application and MCP server name (used in Google Gemini / Claude MCP display and OAuth discovery).	`Acme Backend`
`MOUL_ENCRYPTION_KEY`	Conditional*	—	Master encryption key (min 16 bytes) for `cloak` fields (*required if any collection has a `cloak` field).	`your-secure-32-byte-master-key`
`MOUL_CORS_ORIGINS`	No	`*`	Comma-separated list of allowed CORS origins.	`https://myapp.com,https://admin.myapp.com`
`GEOIP_DB_PATH`	No	—	Path to MaxMind GeoIP2 `.mmdb` database file for visitor analytics.	`/var/lib/moul/GeoLite2-City.mmdb`

S3 & Litestream Replication Variables

Variable	Required	Default	Description
`LITESTREAM_ENABLED`	No	`false`	Enable automated continuous SQLite WAL replication to S3.
`LITESTREAM_S3_BUCKET`	Conditional	—	Target S3 bucket name for backups.
`LITESTREAM_ACCESS_KEY_ID`	Conditional	—	AWS or S3-compatible Access Key ID.
`LITESTREAM_SECRET_ACCESS_KEY`	Conditional	—	AWS or S3-compatible Secret Access Key.
`LITESTREAM_REGION`	No	`us-east-1`	S3 region.
`LITESTREAM_S3_ENDPOINT`	No	—	Custom S3 endpoint (for MinIO, Cloudflare R2, DigitalOcean Spaces).
`LITESTREAM_S3_FORCE_PATH_STYLE`	No	`false`	Enable path-style S3 URLs (required for MinIO).

Local `.env` Template

Create a .env file in your workspace root:

MOUL_ENV=development
MOUL_PORT=8090
MOUL_JWT_SECRET=test-secret-key-for-unit-tests-1234
MOUL_ADMIN_KEY=test-admin-key-1234
MOUL_DB_PATH=moul-local.db
MOUL_PUBLIC_URL=http://localhost:8090
MOUL_ENCRYPTION_KEY=test-encryption-key-for-unit-tests-1234
MOUL_CORS_ORIGINS=*

Many system settings (Email providers, S3 storage, Litestream, OAuth providers, rate limits) can be updated dynamically in the Web Admin Console (/_moul_/settings) or TUI without restarting the binary.

To trigger an immediate server-side hot reload of dynamic configuration:

curl -X POST "http://localhost:8090/api/admin/reload" \
  -H "X-Admin-Key: test-admin-key-1234"

CLI Subcommands Reference

moul includes a rich set of CLI subcommands:

`moul start`

Starts the HTTP daemon and worker engine.

moul start --port 8090 --db /path/to/moul.db

`moul seed`

Seeds demo collections, records, and feature flags.

moul seed --db moul-local.db

`moul mcp`

Launches the native Model Context Protocol (MCP) server over standard input/output (stdio).

moul mcp --db moul-local.db

`moul test-rule`

Evaluates and benchmarks an access rule expression against mock JSON payload and auth context.

moul test-rule \
  --rule="authorId = @request.auth.id && viewsCount > 100" \
  --record='{"authorId": "usr_admin_001", "viewsCount": 1420}' \
  --auth='{"id": "usr_admin_001"}'

`moul worker list-failed` & `moul worker retry`

Inspects and manages the Dead-Letter Queue (DLQ).

# List discarded jobs in dead-letter queue
moul worker list-failed tasks_queue

# Force-retry failed jobs
moul worker retry tasks_queue [optional_job_id]

`moul restore`

Restores a database from S3 backup using Litestream.

moul restore --db /var/lib/moul/moul.db

Configuration & Environment