CLI

Use lux for the local engine and Studio, Lux Cloud projects, migrations, auth and push configuration, diagnostics, updates, remote commands, and interactive connections.

What the CLI is for

The CLI owns the local development lifecycle and is also the operational interface to Lux Cloud. An omitted target means the local engine; pass a project name when a command should target Cloud. Linking a project never silently changes that rule.

Install

Quick install

Detects your OS and architecture automatically, downloads the latest release, and installs to /usr/local/bin.

curl -fsSL https://luxdb.dev/install.sh | sh

GitHub releases

Or download pre-built binaries directly from the GitHub releases page. Binaries are available for macOS (ARM, x86) and Linux (ARM, x86).

Authentication

lux login

This prompts for your token and stores it locally. To log out:

lux logout

Commands

Command	Description
`init`	Create local Lux project files: migrations, seed file, and env example.
`start / studio / stop`	Run and manage the local engine plus Studio. Existing containers never update implicitly.
`login`	Authenticate with your API token
`logout`	Clear stored credentials
`link <project>`	Associate a Cloud project with this directory for explicit Cloud and comparison commands. Omitted operational targets remain local.
`projects`	List all your projects
`create <name>`	Create a new project. Use `--accept-charges` to skip confirmation.
`status [project]`	Show local status by default, or Cloud project status when named.
`doctor [project]`	Check runtime, environment, API compatibility, and migration state. Use `--all` for local plus linked Cloud.
`version / update`	Compare component versions and explicitly update the CLI, local engine, Studio, or a Cloud engine.
`auth provider …`	Configure Google, GitHub, or Apple on the local or an explicitly addressed self-hosted engine.
`exec <name> <cmd>`	Execute a Lux command remotely. Quote wildcards to prevent shell expansion.
`logs <name>`	Tail project logs. Use `-l` to set line count.
`restart <name>`	Restart a project
`destroy <name>`	Permanently delete a project and all its data. Requires `--accept-consequences`.
`connect <target>`	Open an interactive Lux shell. Accepts a project name, `lux://` URL, or `--host` / `--port` flags.
`env pull [project]`	Save the linked or specified Cloud project's app variables as a private profile and optionally activate it in `.env.local`.
`keys list/create/revoke`	Manage Cloud gateway publishable and secret project keys.
`migrate new <name>`	Create a new migration file in `lux/migrations/`.
`migrate status [target]`	Show which migrations are applied vs pending. Target is a project name, `lux://` URL, or `--host` / `--port`. Defaults to the engine managed by `lux start`.
`migrate run [target]`	Run all pending migrations. Same target options as status.
`migrate plan / pull / repair`	Preview engine decisions, synchronize recorded source, and explicitly resolve interrupted migrations.
`push status / apns / vapid`	Inspect and configure native or web push locally or for a named Cloud project.
`seed run [target]`	Run commands from `lux/seed.lux` or a custom seed file.

Configuration

Credentials and settings are stored at:

~/.lux/config.json

Environment variables

Variable	Description
`LUX_API_URL`	Override the default API endpoint
`LUX_ENGINE_URL`	Explicit self-hosted engine HTTP URL for provider administration.
`LUX_ENGINE_PASSWORD`	Operator or secret key paired with `LUX_ENGINE_URL`.
`LUX_PROJECT_ID`	Project selected by `lux env pull` for app code.

Examples

Initialize a Lux project

lux init

# creates:
# lux/migrations/
# lux/seed.lux
# .env.example

Create and connect to a project

lux login
lux create my-app --accept-charges
lux link my-app
lux env pull
lux connect

Pull app environment

lux env pull writes the project URL, auth URL, publishable key, secret key, and direct Lux URL into an env file for app development.

lux link my-app
lux env pull

# or write to a custom path
lux env pull --output .env.development

Run commands remotely

lux exec my-app SET greeting "hello world"
lux exec my-app GET greeting
lux exec my-app "KEYS *"

Monitor and manage

lux status my-app
lux logs my-app -l 100
lux restart my-app

Diagnose versions and update explicitly

lux start reports available updates but never replaces a running engine or Studio implicitly. Cloud engine updates snapshot first and roll back if the new runtime fails its management health check.

lux doctor                 # local stack, API contract, env, migrations
lux doctor my-app          # one Cloud project
lux doctor --all           # local + linked Cloud project
lux version --all          # CLI, local engine, Studio, and linked Cloud

lux update cli
lux update engine          # local engine, preserving its data volume
lux update engine my-app   # snapshot, update, health-check, rollback on failure
lux update studio

OAuth providers

Provider commands target the local engine by default. Use the Cloud dashboard's Auth → Providers page for managed projects. Client secrets and Apple keys are sent directly to encrypted engine storage and are never printed or saved in CLI configuration.

# Local engine by default
lux auth provider google --client-id GOOGLE_CLIENT_ID --client-secret GOOGLE_CLIENT_SECRET
lux auth provider github --client-id GITHUB_CLIENT_ID --client-secret GITHUB_CLIENT_SECRET
lux auth provider apple --bundle-id com.example.app
lux auth provider list

# Remote self-hosted engine
lux auth provider google \
  --url https://db.example.com \
  --password "$LUX_ENGINE_PASSWORD" \
  --client-id GOOGLE_CLIENT_ID \
  --client-secret GOOGLE_CLIENT_SECRET

Migrations

Manage schema changes with versioned migration files. Migrations are .lux files stored in lux/migrations/ and executed line-by-line against your project.

# create and edit a migration
lux migrate new create_users
# edit lux/migrations/20260403_create_users.lux

# run against local project (default localhost:6379)
lux migrate run
lux migrate status

# run against a cloud project
lux migrate run my-app
lux migrate plan my-app
lux migrate pull my-app

# run with a connection string
lux migrate run lux://:password@myhost:6379

# run against a specific host
lux migrate run --host 10.0.0.5 --port 6379

# after reviewing an interrupted migration's command cursor
lux migrate repair 202607280001_create_users.lux resume 1

The migration tracker uses Lux tables under the hood, so lux migrate stays aligned with the table engine rather than a separate schema tool.

Seeds

Seeds are regular Lux command files, useful for local fixtures and demo data.

# default file: lux/seed.lux
lux seed run

# cloud project or direct URL
lux seed run my-app
lux seed run lux://:password@localhost:6379

# custom seed file
lux seed run --file lux/dev.seed.lux

Project keys

Publishable keys are for browser/client gateway requests. Secret keys are for trusted server code only.

lux keys list
lux keys create --kind publishable --name "Browser client"
lux keys create --kind secret --name "Backend worker"
lux keys revoke key_...

Connect to a local project

lux connect lux://localhost:6379
lux connect --host 192.168.1.50 --port 6379

Build on Lux without guessing.

CLI