CLI Reference

The semilayer CLI is the primary way to interact with SemiLayer: configure projects, push schemas, manage sources, generate the typed client, and monitor ingest status.

Installation

npm install -g @semilayer/cli
# or
pnpm add -g @semilayer/cli

Verify with:

semilayer --version

Authentication

Authenticate with SemiLayer Cloud or your enterprise instance.

semilayer login
# Opens browser → Auth0/OIDC → stores credentials in ~/.semilayer/credentials.json

Flag	Description
`--service-url <url>`	Target a self-hosted instance

`semilayer logout`

Clear stored credentials.

semilayer logout

`semilayer whoami`

Show the currently authenticated user.

semilayer whoami

Project Setup

`semilayer init`

Interactive wizard — select or create an org, project, and environment. Saves context to .semilayerrc and optionally creates a starter sl.config.ts.

semilayer init

Run this first when setting up a new codebase. The .semilayerrc file tells all subsequent CLI commands which org/project/environment to target.

Flag	Description
`--service-url <url>`	Override the service API URL

`semilayer config`

View or update the active context (org, project, environment, service URL).

semilayer config             # show current context
semilayer config --set-env production
semilayer config --set-project my-app

Schema

`semilayer push`

Push your sl.config.ts to the service. Registers new lenses, updates changed ones, and marks removed ones for cleanup.

semilayer push                            # push schema only (lenses start paused)
semilayer push --resume-ingest            # push and immediately start ingest
semilayer push --rebuild                  # push and full re-index all lenses
semilayer push --force                    # skip drift detection warning

Flag	Description
`--resume-ingest`	Start ingest for new/modified lenses after push
`--rebuild`	Full re-index for ALL lenses (clears existing data — prompts for confirmation)
`--skip-confirmation-dangerously`	Skip rebuild confirmation for CI/CD
`--force`	Skip drift detection — push even if Console has newer changes

Drift detection runs automatically on every push. If the Console has modified a lens since your last push, you'll see a warning and a confirmation prompt.

`semilayer export config`

Pull the remote config back to your local sl.config.ts. Useful when the Console has changes you want to sync back to code.

semilayer export config

`semilayer status`

Show lens statuses, ingest queue, and (in SaaS mode) quota usage.

semilayer status

Output:

  Environment: development (my-app / my-org)

  Lenses:
    products    ready       42,301 vectors
    articles    indexing    18,092 vectors
    users       paused      0 vectors

  Queue:
    Active: 1  Pending: 0  Failed: 0  Completed (24h): 12

Code Generation

`semilayer generate`

Generate the typed Beam client from your sl.config.ts. Outputs TypeScript files to ./generated/semilayer/ by default.

semilayer generate
semilayer generate --out ./src/semilayer

Flag	Default	Description
`--out <dir>`	`./generated/semilayer`	Output directory

The generated module exports a createBeam factory and a Beam class, both fully typed against your lens definitions. See Beam Client.

Ingest Control

`semilayer pause`

Pause ingest for one or all lenses.

semilayer pause               # pause all lenses
semilayer pause --lens products

`semilayer resume`

Resume ingest for one or all lenses.

semilayer resume              # resume all lenses
semilayer resume --lens products

`semilayer sync`

Trigger a one-off incremental sync for a lens (or all lenses).

semilayer sync
semilayer sync --lens products

Streaming

`semilayer stream`

Subscribe to a live tail for a lens and print events to stdout.

semilayer stream --lens products

`semilayer observe`

Watch a single record for changes.

semilayer observe --lens products --id 42

Sources

`semilayer sources connect`

Interactively connect a new data source and introspect available targets.

semilayer sources connect

Prompts for a bridge package, connection details, and a name. Stores the source in your current environment. Lists available tables/collections/endpoints after connecting.

`semilayer sources list`

semilayer sources list

`semilayer sources remove`

semilayer sources remove --name main-db

Organization Management

These commands manage your org, projects, environments, members, and API keys from the terminal.

# Orgs
semilayer orgs list
semilayer orgs create

# Projects
semilayer projects list
semilayer projects create

# Environments
semilayer envs list
semilayer envs create

# API Keys
semilayer keys list
semilayer keys create --type service --label my-backend
semilayer keys revoke --id <key-id>

# Members
semilayer members list
semilayer members invite --email alice@example.com --role developer
semilayer members remove --email alice@example.com

Billing (SaaS)

semilayer billing status      # current plan and quota usage
semilayer billing upgrade     # open the upgrade flow in the browser

Global Flags

--help / -h — Show help for any command.

--version / -v — Show the CLI version.

Config File

The .semilayerrc file in your project root (or any parent directory) stores context:

{
  "orgSlug": "my-org",
  "projectSlug": "my-app",
  "envSlug": "development",
  "serviceUrl": "https://api.semilayer.com"
}

The CLI walks up the directory tree to find the nearest .semilayerrc. Credentials (auth tokens) are stored separately in ~/.semilayer/credentials.json.