npm package: @schemalens/cli
Description: SchemaLens CLI — pull, diff, and deploy PostgreSQL schemas
Latest version: 0.7.0

# @schemalens/cli

Schema version control for PostgreSQL and Supabase — CLI tool.

## Installation

```bash
npm install -g @schemalens/cli
```

## Setup

Run the interactive setup wizard in your project root:

```bash
schemalens init
```

This creates `schema/_meta/.schemalens.yml`. Commit this file to your repository.

## Commands

### `schemalens pull --env <env>`

Introspects the live database and writes schema files to `schema/`.

```bash
schemalens pull --env dev
schemalens pull --env staging
```

### `schemalens status --env <env>`

Shows what's different between your local schema files and the live database. Does not make any changes.

```bash
schemalens status --env dev
```

Output:
```
+ 2 new objects
  + [table] public.audit_logs
  + [function] public.get_audit_summary

~ 1 changed objects
  ~ [table] public.users

= 142 objects unchanged
```

### `schemalens deploy --env <env>`

Plans and (optionally) applies your local schema changes to the target database.

```bash
# Dry run — shows the plan without executing (default)
schemalens deploy --env staging

# Apply changes
schemalens deploy --env staging --confirm

# Allow destructive operations (DROP COLUMN, DROP TABLE, etc.)
schemalens deploy --env staging --confirm --allow-destructive

# Confirm a column rename (prevents DROP + ADD)
schemalens deploy --env staging --confirm --rename users.name:full_name
```

### `schemalens init`

Interactive project setup — creates `schema/_meta/.schemalens.yml`.

---

## Configuration

```yaml
# schema/_meta/.schemalens.yml
version: 1
schema_dir: schema
allow_destructive: false

environments:
  dev:
    connection_string: env(DATABASE_URL)       # reads $DATABASE_URL
  staging:
    connection_string: env(DATABASE_URL_STAGING)
  prod:
    # Omit connection_string to use linked mode (see below)

# SchemaLens SaaS integration (optional)
project_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
api_key: env(SCHEMALENS_API_KEY)
```

### `env(VAR_NAME)` syntax

Any config value can reference an environment variable:

```yaml
connection_string: env(DATABASE_URL)
```

The CLI resolves `env(DATABASE_URL)` to the value of `$DATABASE_URL` at runtime. If the variable is not set, the CLI exits with a clear error.

### Linked mode (no local DATABASE_URL needed)

When `project_id` and `api_key` are both set, you can omit `connection_string` from any environment. The CLI will fetch the connection details from SchemaLens SaaS using your API key.

```yaml
environments:
  prod: {}          # no connection_string — uses SaaS credentials

project_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
api_key: env(SCHEMALENS_API_KEY)
```

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `DATABASE_URL` | Yes (unless linked mode) | PostgreSQL connection string |
| `SCHEMALENS_API_KEY` | Optional | API key for SaaS sync + linked mode |
| `SCHEMALENS_API_URL` | Optional | Override SaaS API base URL (default: `https://schemalens.vercel.app`) |

---

## Schema Directory Structure

```
schema/
├── _meta/
│   ├── .schemalens.yml     # config (commit this)
│   └── deploy.log          # local deploy history
├── extensions/
│   └── enabled.sql
├── enums/
│   └── <name>.sql
├── tables/
│   └── <table>/
│       ├── definition.sql
│       ├── indexes.sql
│       ├── policies.sql
│       └── triggers.sql
├── views/
│   └── <name>.sql
└── functions/
    └── <name>.sql
```

All files under `schema/` should be committed to your repository. They are the source of truth for `schemalens deploy`.