CLI Reference

The Maravilla CLI is a command-line tool that provides development, build, preview, and platform management commands for your projects.

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:

Flag	Short	Description
`--quiet`	`-q`	Suppress output
`--debug`		Enable debug logging (sets `MARAVILLA_DEBUG_FETCH=1` and verbose tracing)
`--version`	`-V`	Show version
`--help`	`-h`	Show help

`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

Flag	Description
`--skip-install`	Skip installing dependencies after initialization
`--force`	Force initialization even if already initialized

Example:

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

`maravilla dev`

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

maravilla dev

Flag	Short	Default	Description
`--port`	`-p`	`3001`	Port for the platform dev server
`--tenant`	`-t`		Tenant ID for development
`--open`			Open browser after starting

Example:

maravilla dev --port 8080 --open

`maravilla build`

Build your application for production. Detects your framework adapter automatically and produces an optimized output bundle.

maravilla build

Flag	Short	Default	Description
`--adapter`	`-a`	auto-detect	Framework adapter to use
`--check`			Validate build output
`--snapshot`			Generate snapshot for faster cold starts
`--snapshot-output`			Custom output name for the snapshot file (e.g., `server.bin`)

Examples:

# Standard production build
maravilla build

# Build with snapshot for faster cold starts
maravilla build --snapshot

# Build and validate output
maravilla build --check

# Specify a custom snapshot output path
maravilla build --snapshot --snapshot-output my-server.bin

`maravilla preview`

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

maravilla preview

Flag	Short	Default	Description
`--port`	`-p`	`3000`	Port for the preview server
`--snapshot`			Use snapshot instead of JavaScript bundle
`--snapshot-path`		`.maravilla/server.bin`	Path to snapshot file
`--auto-snapshot`			Automatically create and promote snapshots locally
`--build-dir`		`.maravilla`	Build directory
`--production-mode`			Use production policies instead of development
`--memory-limit`			Set memory limit in MB
`--timeout`			Set request timeout in seconds
`--max-rps`			Set max requests per second

Examples:

# Preview on a custom port
maravilla preview --port 4000

# Preview with snapshot
maravilla preview --snapshot

# 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. Requires the dev server to be running.

maravilla platform kv

Flag	Short	Default	Description
`--namespace`	`-n`		KV namespace to browse
`--url`		`http://localhost:3001`	Dev server URL

Example:

maravilla platform kv --namespace sessions --url http://localhost:3001

`maravilla platform db`

Browse database collections interactively using a terminal UI. Requires the dev server to be running.

maravilla platform db

Flag	Short	Default	Description
`--collection`	`-c`		Collection to browse
`--url`		`http://localhost:3001`	Dev server URL

Example:

maravilla platform db --collection users

`maravilla login`

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 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

Flag	Short	Description
`--environment`	`-e`	Target environment (defaults to `production`)
`--dry-run`		Perform a dry run without deploying

Typical Workflow

# 1. Initialize your project
maravilla init

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

# 3. Build for production
maravilla build --snapshot

# 4. Preview the production build locally
maravilla preview --snapshot

# 5. Authenticate and deploy
maravilla login
maravilla deploy