CLI Reference

The Maravilla CLI provides development, preview, and platform management commands for your projects. Build your project with your framework’s normal command (npm run build); use the CLI for everything around it.

Installation

npm install -g @maravilla-labs/cli

Binaries are published for:

• Linux: x86_64-unknown-linux-gnu
• macOS: x86_64-apple-darwin, aarch64-apple-darwin (Intel and Apple Silicon)
• Windows: x86_64-pc-windows-msvc

Global Flags

These flags can be used with any command:

maravilla init [path]

Initialize Maravilla in an existing project. Creates the .maravilla/ configuration directory and installs the required adapter for your framework.

# Initialize in the current directory
maravilla init

# Initialize in a specific directory
maravilla init ./my-project

Example:

maravilla init --force ./my-astro-app

maravilla dev

Start a development server with hot reload. The platform services (KV store, database, storage, realtime) are available locally during development.

The dev server reads maravilla.config.{ts,js,mjs,yaml,yml,json} directly from your project root at boot — no build step required. Auth pages (/_auth/login, /_auth/register) and database indexes are derived from this config and reflect changes after a restart.

maravilla dev

Example:

maravilla dev --port 8080 --open

When dev boots, it runs maravilla doctor silently and surfaces any setup gaps as warnings. Boot is never blocked — fix at your own pace, or run maravilla doctor --fix.

Hooking up the dev server. Add @maravilla-labs/vite-plugin to your vite.config.ts so platform routes work alongside your framework dev server. maravilla doctor will flag it if it’s missing.

maravilla doctor

Diagnose your Maravilla setup. Read-only by default — scans for missing adapter, missing Vite plugin, missing maravilla.config.*, and unwired adapter/plugin references in your framework configs. Exits non-zero on errors so it’s CI-friendly.

maravilla doctor

What gets checked:

• package.json exists at project root
• A supported framework is detected (SvelteKit, React Router 7, Nuxt)
• The matching adapter is installed (@maravilla-labs/adapter-{sveltekit,react-router}, etc.)
• @maravilla-labs/adapter-core resolves in node_modules
• A maravilla.config.{ts,js,mjs,yaml,yml,json} file exists
• @maravilla-labs/vite-plugin is installed
• The adapter is referenced in svelte.config.js / react-router.config.ts / nuxt.config.ts
• maravilla() is called in vite.config.ts plugins array

Examples:

# Read-only scan
maravilla doctor

# Autofix what's safe
maravilla doctor --fix

# CI usage — exits non-zero on Error severity
maravilla doctor --quiet || exit 1

Building your project

Use your framework’s standard build command:

npm run build

The Maravilla framework adapter hooks into your build and produces a deploy-ready build/ directory. From there, use maravilla preview to test it locally.

maravilla check

Validate that a build output directory contains the expected files (manifest.json, server.js, static/, optionally server.bin). Useful in CI to catch missing artefacts before deploy.

maravilla check

Example:

maravilla check --out build

maravilla preview

Preview a production build locally. Runs the built application using the same runtime environment as production.

maravilla preview

Examples:

# Preview on a custom port (auto-detects build/ or .maravilla/)
maravilla preview --port 4000

# Preview from a non-standard build dir
maravilla preview dist

# Preview with production-like resource limits
maravilla preview --production-mode --memory-limit 128 --timeout 30 --max-rps 100

maravilla platform status

Show the status of platform services (KV store, database) for the current project.

maravilla platform status

maravilla platform kv

Browse the KV store interactively using a terminal UI. Targets the local dev server by default; pass --cloud to browse your deployed project’s cloud KV store instead.

maravilla platform kv

Examples:

# Browse a namespace on the local dev server
maravilla platform kv --namespace sessions

# Browse the same namespace in cloud (production data)
maravilla platform kv --namespace sessions --cloud

maravilla platform db

Browse database collections interactively using a terminal UI. Targets the local dev server by default; pass --cloud to browse your deployed project’s cloud database instead.

maravilla platform db

Examples:

# Browse a specific collection on the local dev server
maravilla platform db --collection users

# Browse the same collection in cloud (production data)
maravilla platform db --collection users --cloud

maravilla platform index

Manage MongoDB-style secondary indexes on the database. Indexes speed up find() queries on frequently-filtered fields. See Database › Indexes for when to use each option.

# Create a single-field index
maravilla platform index create users --keys "email" --unique

# Compound index with mixed directions
maravilla platform index create posts --keys "authorId,createdAt:-1"

# Partial index (JSON predicate)
maravilla platform index create posts --keys "category" \
  --partial '{"status": "published"}'

# TTL index — auto-deletes docs after N seconds
maravilla platform index create sessions --keys "createdAt" \
  --expire-after-seconds 3600

# List every index (document + vector) on a collection
maravilla platform index list users

# Drop an index by name
maravilla platform index drop users users_email_unique

The --keys flag takes a comma-separated field[:dir] list. Directions: 1/asc (default) or -1/desc.

maravilla platform vector

Manage and query vector indexes. See Vector Search for the full feature reference.

# Create a vector index
maravilla platform vector create-index products embedding \
  --dimensions 1536 --metric cosine --storage int8

# Search from the terminal
maravilla platform vector search products embedding \
  --vector '[0.1, 0.2, 0.3, ...]' --k 10

# Search with a metadata pre-filter
maravilla platform vector search products embedding \
  --vector '[0.1, 0.2, ...]' --k 10 \
  --filter '{"category": "electronics"}'

# List vector indexes
maravilla platform vector list products

# Drop an index
maravilla platform vector drop-index products embedding

maravilla login

Log in to Maravilla Cloud. Opens an interactive authentication flow.

maravilla login

maravilla register

Create a new Maravilla Cloud account.

maravilla register

maravilla logout

Log out from Maravilla Cloud and clear stored credentials.

maravilla logout

maravilla whoami

Show the current authentication status and logged-in user.

maravilla whoami

maravilla auth

Push (or preview) the auth settings declared in your maravilla.config.{ts,yaml,json} against the server, without going through a full build-and-deploy cycle. See the Authorization guide for the config file schema.

Both subcommands read your built manifest.json — run npm run build (your framework’s build, which invokes the Maravilla adapter) first. The default path is build/manifest.json; older projects may have it at .maravilla/manifest.json. Pass --manifest <path> if it lives elsewhere.

maravilla auth diff

Show what auth sync would change, without writing anything. Exits non-zero when there are differences — wire it into CI to gate PRs on config drift.

maravilla auth diff --project <project-id>

Example output:

To create:
  + resources todos
To update:
  ~ groups moderators
  ~ branding
DB-only (kept on sync):
  ? resources legacy_docs
● 1 item(s) unchanged

maravilla auth sync

Apply the config. Upserts resources/groups/relations by natural key; replaces registration fields, OAuth providers, security policy, and branding. UI-authored items not in your config are kept — never auto-deleted.

maravilla auth sync --project <project-id>

Safe to re-run — it’s an upsert, not a replace.

Example:

npm run build
maravilla auth sync --project prj_abc123

OAuth client_secret values with ${env.VAR} / { env: "VAR" } syntax are resolved from your local environment before being sent — never plaintext in the repo.

maravilla auth status

Show the active session, account email, token expiry, and configured git helper state. Read-only — useful as a first check when something auth-related stops working.

maravilla auth status

maravilla auth refresh-token

Force-refresh the current Maravilla Cloud access token using the stored refresh token. Normally the CLI refreshes on demand; run this explicitly to verify the refresh path or to recover from a stale token without a full logout / login cycle.

maravilla auth refresh-token

maravilla auth setup-git

Register maravilla auth git-credential as a credential helper in your global ~/.gitconfig so git clone / git push / git pull against Maravilla Git (Muli) work without typing a password. Run once after maravilla login.

maravilla auth setup-git

This writes a credential.https://git.maravilla.app section that delegates to maravilla auth git-credential. Undo it with maravilla logout --remove-git-helper.

maravilla auth git-credential

Internal helper invoked by git over the credential helper protocol. You don’t call this directly — git does, once maravilla auth setup-git has wired it up.

When invoked it reads the current Maravilla Cloud session and emits a short-lived Personal Access Token scoped to your user. Parallel git push invocations are serialized through an advisory file lock on ~/.maravilla/muli-tokens.toml so they don’t race to refresh the cached PAT.

maravilla policy

Local, offline tooling for authorization policies. No login or network needed.

maravilla policy test

Evaluate REL policies against a fixture file of {auth, node} → expected cases, using the same evaluator the runtime uses — so a fixture that passes behaves identically in production (RELATES traversal included). Exits non-zero if any case fails, which makes it CI-friendly.

maravilla policy test

The fixture file declares an optional top-level policy, an optional relations edge list (feeds the relation resolver so RELATES clauses resolve offline), and a list of cases — each with name, auth, node, expected ("allow" / "deny"), and an optional per-case policy override. A policy that fails to parse evaluates as deny, so you can assert that a malformed policy denies.

// policy.fixtures.json
{
  "policy": "auth.user_id == node.owner || auth.is_admin",
  "relations": [
    { "source": "guardian", "target": "ward", "via": "STEWARDS" }
  ],
  "cases": [
    { "name": "owner reads",  "auth": { "user_id": "u1" }, "node": { "owner": "u1" }, "expected": "allow" },
    { "name": "stranger denied", "auth": { "user_id": "u2" }, "node": { "owner": "u1" }, "expected": "deny" }
  ]
}

maravilla policy test --fixtures auth.fixtures.json
maravilla policy test --policy "auth.is_admin" --bail

maravilla resources

maravilla resources doctor

Audit the resources declared in your built manifest.json for (resource_name, service_type) hazards: the same name declared with two different concrete service types (cross-service collision), and a name declared both typed and untyped (ambiguous fallback). Run your framework build first so the adapter has emitted the manifest.

npm run build
maravilla resources doctor

The report lists each resource with its service type and whether it carries a policy, flagging any collisions or ambiguous fallbacks. (The cross-check of declared resources against the bindings your handler code actually references needs runtime coverage data that isn’t available offline, so it’s skipped.)

maravilla resources doctor --strict

maravilla pr

PR-level commands against Maravilla Git (Muli) for projects hosted on Maravilla Cloud.

maravilla pr list
maravilla pr view 42
maravilla pr create --title "Fix login redirect" --body "…"
maravilla pr merge 42 --squash

Examples:

# What pipelines did this PR kick off?
maravilla pr checks 42

# Convert a draft to ready and add a comment in one breath
maravilla pr ready 42
maravilla pr comment 42 --body "Ready for review."

# Drop into a reviewer's PR locally
maravilla pr checkout 42

maravilla issue

Project issues against Flightdeck for projects hosted on Maravilla Cloud.

maravilla issue list --state open --label bug
maravilla issue view 123 --comments
maravilla issue create --title "Login redirect loops" --label bug --priority high
maravilla issue close 123 --comment "Fixed in PR #42."

Issue commands accept --project <id|namespace/repo> to target a different project than the current repo. Without it, the CLI infers the project from the git remote.

maravilla repo

Repo-level commands against Maravilla Git (Muli).

maravilla repo list
maravilla repo create my-app --private
maravilla repo clone my-org/my-app
maravilla repo view my-org/my-app
maravilla repo sync

maravilla browse [target]

Open the current repo, a PR, a branch, or a file in your default browser. With no argument, opens the repo root.

# Open the repo
maravilla browse

# Open PR #42
maravilla browse 42

# Open a branch
maravilla browse feature/new-login

# Open a file at HEAD
maravilla browse src/routes/+page.svelte

maravilla variable

Manage plain (non-encrypted) environment variables on the current project or an org. Mirrors gh variable — same subcommand names, same flags. The project is auto-detected from the git remote.

maravilla variable list                            # project, default env slot
maravilla variable list --env production           # project, production slot
maravilla variable list --org acme                 # org-scope
maravilla variable get DATABASE_HOST
maravilla variable set DATABASE_HOST --body db.internal.example.com
maravilla variable set --env-file .env             # bulk import
maravilla variable delete DATABASE_HOST --yes

Every entry has three independent env slots (default, production, preview) so you can set distinct values per environment without separate keys.

.env parsing handles comments (#), blank lines, export KEY=value, and single- or double-quoted values.

Examples:

# Pipe a value in (great in CI)
echo "$DATABASE_HOST" | maravilla variable set DATABASE_HOST --env production

# Import all values into the production slot
maravilla variable set --env-file .env.production --env production

# Org-wide value visible to every project in the org
maravilla variable set BRAND_DOMAIN --body example.com --org acme

maravilla secret

Manage encrypted secrets — same shape as maravilla variable, but values are AES-256-GCM-encrypted at rest and gated behind a vault password. Mirrors gh secret.

maravilla secret list                           # metadata only, no values printed
maravilla secret set STRIPE_API_KEY             # prompts for value + vault password
maravilla secret set STRIPE_API_KEY --body "sk_live_…" --env production
maravilla secret set --env-file .env.production # bulk import; one vault prompt total
maravilla secret delete STRIPE_API_KEY --yes

There is no secret get — by design, mirroring gh secret. To read decrypted values, use maravilla env list --show-secrets.

The vault password is prompted interactively, never read from an env var, never persisted to disk — same flow the web dashboard uses to unlock secret access.

Examples:

# Set a production-only secret without echoing it
maravilla secret set STRIPE_API_KEY --env production
#   (typed into the masked prompt, then the vault prompt)

# CI usage — pipe the value in, still get prompted for the vault password
printf '%s' "$STRIPE_KEY" | maravilla secret set STRIPE_API_KEY --env production

# Migrate every value in a local .env to the preview slot of an org secret store
maravilla secret set --env-file .env.preview --env preview --org acme

maravilla env

Read-only view of the merged org → project env cascade that a build will actually see.

maravilla env list

maravilla env list                          # default slot, secrets redacted
maravilla env list --env production         # production slot
maravilla env list --env production --show-secrets   # decrypt secrets
maravilla env list --json

The SOURCE column shows whether a value came from org or project scope — project values always override org values for the same key. The KIND column distinguishes variable (plain) from secret (encrypted).

$ maravilla env list --env production
  KEY              KIND      SOURCE   VALUE
  BRAND_DOMAIN     variable  org      example.com
  DATABASE_URL     secret    project  ***
  PUBLIC_API_BASE  variable  project  https://api.example.com

maravilla update

Update the Maravilla CLI binary to the latest version.

maravilla update

maravilla deploy

Deploy your application to a target environment. This command is under active development.

maravilla deploy

Typical Workflow

# 1. Initialize your project
maravilla init

# 2. Develop with hot reload
maravilla dev --open

# 3. Build for production (your framework's build runs the Maravilla adapter)
npm run build

# 4. Preview the production build locally
maravilla preview

# 5. Authenticate and deploy
maravilla login
maravilla deploy

Iterating on auth settings

If your project has a maravilla.config.* declaring auth resources, groups, policies, or branding, you can push changes to an existing project without waiting on a full build-and-deploy:

# Rebuild so manifest.json is current
npm run build

# See what's different
maravilla auth diff --project prj_abc123

# Apply it
maravilla auth sync --project prj_abc123