Skip to main content

CLI and bootstrap

Self-hosted deployments use vlunactl for bootstrap and provisioning tasks.

Prereqs​

  • You have a running deployment and Postgres.
  • You have:
    • DATABASE_MIGRATOR_URI
    • VLUNA_PLANE (for OSS/Enterprise use vluna; admin reserved)
    • VLUNA_DB_SCHEMA (default control_plane)
    • BILLING_MASTER_KEY

Common commands​

List realms​

cd vluna/oss
pnpm vlunactl realm list

Create a realm​

cd vluna/oss
pnpm vlunactl realm create --realm-id realm-default --name 'Demo Realm'

Optional metadata:

cd vluna/oss
pnpm vlunactl realm create \
  --realm-id realm-default \
  --name 'Demo Realm' \
  --metadata-json '{
    "auth": {
      "issuers": [
        {
          "issuer": "https://issuer.example",
          "audiences": ["your-audience"],
          "jwks_uri": "https://issuer.example/.well-known/jwks.json"
        }
      ]
    },
    "payments": {
      "stripe": {
        "mode": "test",
        "api_keys": { "test": "sk_test_xxx" },
        "webhooks": [{ "name": "payment", "test": "whsec_xxx" }],
        "public_webhook_base_url": "https://example.com"
      }
    }
  }'

Create a service key and derive the secret​

cd vluna/oss
pnpm vlunactl service-key create --realm-id realm-default
pnpm vlunactl service-key create --realm-id realm-default --expires-at 2026-06-30T00:00:00Z
pnpm vlunactl service-key secret --realm-id realm-default --key-id pk_example

When calling /mgt/v1 with the service key, include X-Realm-Id and set X-Realm-Admin: true for realm admin RLS.

Next​