CLI Commands

Complete reference for all Astroladb (alab) CLI commands.

---

Development Commands

alab init

Initialize a new project. Creates schemas/, migrations/, and types/ directories along with an alab.yaml config file.

alab init

Use --demo to scaffold a sample schema:

alab init --demo

alab table

Create a new table schema file. Takes a namespace and table name.

alab table auth user

This creates schemas/auth/user.js.

alab live

Start a local server for live API documentation. Useful for browsing your schema interactively.

alab live

alab export

Export the schema in a given format.

alab export -f openapi
alab export -f graphql
alab export -f typescript
alab export -f python
alab export -f go
alab export -f rust

# Include relationship fields (WithRelations variants)
alab export -f typescript --relations

Flag	Description
-f	Required. Format: openapi, graphql, typescript, go, python, rust
--relations	Generate WithRelations type variants with relationship fields
--namespace	Filter export to a specific namespace

---

Migration Commands

alab new

Generate a migration from the current schema diff. The argument is a descriptive name for the migration.

alab new create_users

alab migrate

Apply all pending migrations.

alab migrate

Preview the SQL without applying (shows phase-by-phase execution plan with estimates):

alab migrate --dry

Dry-run output includes:

• Phase-by-phase SQL (DDL → Index → Data)
• Row count estimates for affected tables
• Time estimates for each phase
• Total migration time estimate

Apply and auto-commit to git:

alab migrate --commit

Verify SQL checksums before applying:

alab migrate --verify-sql

Flag	Description
--dry	Show phase-by-phase SQL with row/time estimates (no execution)
--force	Skip safety warnings and confirmation prompts
--confirm-destroy	Confirm DROP operations
--commit	Auto-commit migration files to git after apply
--skip-lock	Skip distributed locking (use in CI)
--lock-timeout	Lock acquisition timeout (default 30s)
--verify-sql	Verify SQL checksums against stored values first

alab rollback

Roll back the most recent migration. Pass a number to roll back multiple steps.

alab rollback
alab rollback 3

alab check

Validate schema files or lint migration files for safety issues.

# Validate all schema files
alab check

# Lint migration files for destructive operations, missing defaults, etc.
alab check --migrations

# Verify SQL determinism for applied migrations
alab check --determinism

Flag	Description
--migrations	Lint migration files instead of validating schemas
--determinism	Re-generate SQL for applied migrations and compare checksums

Schema validation (default)

Loads all schema files through the sandbox and runs structural validation — missing primary keys, invalid column types, broken references, duplicate definitions, etc. Exits with code 1 on any error.

Migration linting (--migrations)

Scans migration operations and warns about:

Rule	Trigger	Message
Drop table	m.drop_table()	Will DELETE ALL DATA in table
Drop column	m.drop_column()	Will DELETE DATA in column
NOT NULL without default	m.add_column() with a NOT NULL column that has no default(), backfill(), or server_default()	NOT NULL column has no default or backfill value
Reserved SQL word	Table or column name matches a SQL reserved word (user, order, type, select, etc.)	Identifier is a SQL reserved word
Lock file integrity	alab.lock checksum mismatch	Lock file is out of date or tampered

Exits with code 1 if any warnings are found. Use --force on alab migrate to proceed despite warnings.

SQL determinism (--determinism)

Re-parses each applied migration, re-generates its SQL, and compares the SHA-256 hash against the sql_checksum stored in alab_migrations at apply time. Reports any migration that would produce different DDL today than it did when originally applied — catches non-deterministic migrations (e.g. those using Date.now() or environment-dependent logic).

alab squash

Collapse all migrations into a single baseline migration. Useful after accumulating many migrations over time.

# Preview what would be squashed
alab squash --dry-run

# Squash all migrations into a baseline
alab squash

Old migration files are archived to .alab/archive/. Existing environments skip the baseline automatically; new environments apply only the baseline.

---

Toolkit Commands

alab schema

Show the schema at a specific migration revision.

alab schema

alab status

Show schema state, migration history, verification, and drift detection in a TUI.

alab status

alab types

Regenerate TypeScript definitions used for IDE autocompletion inside schema files.

alab types

alab lock

Manage the migration lock file (alab.lock).

# Show lock status
alab lock status

# Verify lock file integrity
alab lock verify

# Regenerate lock file from migration files
alab lock repair

# Force-release a stuck migration lock
alab lock release --force

---

Generator Commands

alab gen run

Run a generator file and write the output to a directory.

alab gen run generators/fastapi -o ./generated

The .js extension is optional.

Flag	Description
-o, --output	Required. Output directory.

alab gen add

Download a shared generator from a URL into generators/.

alab gen add https://raw.githubusercontent.com/hlop3z/astroladb/main/examples/generators/generators/fastapi.js

See Code Generators for the full generator API and sandbox reference.