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 → OIDC sign-in → 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 manual smart sync for a lens (or all lenses) — full scan with content-hash dedup and tombstone detection. Same handler the Console "Sync now" button invokes.

semilayer sync
semilayer sync --lens products

Manual runs count against the same smart_sync_jobs monthly tier quota as scheduled runs from smartSyncInterval. A 429 response with error: 'SMART_SYNC_QUOTA_EXHAUSTED' means you've hit the cap for this billing cycle — check semilayer status for the current counter, or upgrade via semilayer billing.

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

Count

`semilayer count <lens>`

Count rows on a lens matching a where predicate. Sibling of query for "how many" questions — uses the bridge's native count when available.

semilayer count recipes --api-key sk_dev_...
semilayer count orders --where '{"status":"failed"}' --api-key sk_...
semilayer count carts \
  --where '{"$or":[{"abandoned":true},{"itemCount":{"$gte":10}}]}' \
  --api-key sk_...

  1,842 rows
  lens: orders
  strategy: native
  durationMs: 6

Flag	Description
`--api-key <key>`	sk_ or pk_ key (required)
`--where <json>`	JSON predicate. Same grammar as `query` — supports `$or`, `$and`, `$not`, `$in`, `$gte`, `$ilike`, etc.
`--exit-code`	Exit with the count itself (clamped to 0–255) for shell branching: `count … --exit-code && alert`.
`--json`	Print the raw `CountResponse` body.
`--service-url <url>`	Override service URL.

Analyze

The semilayer analyze command group drives the analyze facet — list, run, drill into, explain, and tune named analyses. Lens-analysis identifier is <lens>.<analysisName> (mirrors how Beam emits them).

`semilayer analyze list <lens>`

List the named analyses declared on a lens.

semilayer analyze list recipes --api-key sk_dev_...

  Lens:  recipes
  Analyses:  3

  NAME              KIND     DIMS        MEASURES
  byCuisine         metric   cuisine     count, avgRating
  signupFunnel      funnel   ─           ─
  retentionByMonth  cohort   ─           ─

Flag	Description
`--api-key <key>`	sk_ or pk_ key (required)

`semilayer analyze run <lens.name>`

Run an analysis once and print buckets + totals.

semilayer analyze run recipes.byCuisine --api-key sk_...
semilayer analyze run recipes.byCuisine --input @input.json --json
semilayer analyze run recipes.byCuisine --cache no-cache
semilayer analyze run recipes.byCuisine --ndjson

Flag	Description
`--api-key <key>`	sk_ or pk_ key (required)
`--input <json>`	Inline JSON body or `@path/to/file.json`
`--cache <directive>`	Pass-through to the `Cache-Control` header — e.g. `no-cache` to force a recompute
`--json`	Print the raw `AnalyzeResult` body
`--ndjson`	Emit one bucket per line (NDJSON) — pairs with shell pipelines

`semilayer analyze rows <lens.name>`

Drill into one bucket — fetch the contributing rows, paginate via cursor or stream the whole set out.

# Drill — paginated table
semilayer analyze rows recipes.byCuisine \
  --bucket "$BUCKET_KEY" --limit 25 --api-key sk_...

# Search inside the bucket
semilayer analyze rows recipes.byCuisine \
  --bucket "$BUCKET_KEY" --search "spicy comfort" --api-key sk_...

# Sort — repeat the flag for multi-key sort. PK appended server-side.
semilayer analyze rows products.byCategory \
  --bucket "$BUCKET_KEY" --sort price:desc --sort name --api-key sk_...

# Stream the full set as NDJSON
semilayer analyze rows recipes.byCuisine \
  --bucket "$BUCKET_KEY" \
  --export rows.ndjson --format ndjson \
  --api-key sk_...

# Pipe through wc -l to verify
semilayer analyze rows recipes.byCuisine \
  --bucket "$BUCKET_KEY" --export - --format ndjson --api-key sk_... \
  | wc -l

Flag	Description
`--api-key <key>`	sk_ or pk_ key (required)
`--bucket <key>`	`bucketKey` from a bucket in `analyze run` (required)
`--cursor <token>`	Cursor returned by the previous page
`--limit <n>`	Page size (default 100, max 1000)
`--search <q>`	Free-text query inside the bucket
`--search-mode <mode>`	`auto` \| `simple` \| `semantic` \| `hybrid` (default `auto`)
`--sort <col[:dir]>`	Sort field, optionally with `:asc` or `:desc`. Repeatable for multi-key sort
`--export <path>`	Stream all matching rows to a file; `-` for stdout. Pairs with `--format`
`--format <fmt>`	`ndjson` or `csv` (default `ndjson`) — applies only when `--export` is set
`--json`	Output raw JSON instead of a table (page mode)

`semilayer analyze explain <lens.name>`

Full execution plan + cache decision for one analyze. Requires an sk_ key — pk_ keys are rejected client-side before the request fires.

semilayer analyze explain recipes.byCuisine --api-key sk_... --input @input.json

Flag	Description
`--api-key <key>`	Service key (sk_) — pk_ rejected
`--input <json>`	Inline JSON body or `@path/to/file.json`
`--json`	Output raw JSON

`semilayer analyze plan <lens.name>`

Print source-DB index recommendations for an analysis. sk_ only.

semilayer analyze plan products.byCategory --api-key sk_...
semilayer analyze plan products.byCategory --api-key sk_... --sql > pg.sql

Flag	Description
`--api-key <key>`	Service key (sk_)
`--json`	Output raw JSON
`--sql`	Print only the DDL statements (pipe-friendly)

Feeds

The semilayer feed command group drives the feed facet — list, fetch, tail, and explain named feeds without going through Beam codegen.

The lens-feed identifier is <lens>.<feedName> (mirrors how Beam emits them).

`semilayer feed list <lens>`

List the named feeds declared on a lens.

semilayer feed list posts --api-key sk_dev_...

  Lens:  posts
  Feeds:  3

  NAME       RULE    CANDIDATES  PAGE  SCORERS
  discover   public  embeddings  12    similarity+recency+engagement
  latest     public  recent      20    recency
  relatedTo  public  embeddings  6     similarity

Flag	Description
`--api-key <key>`	sk_ or pk_ key (required)

`semilayer feed view <lens.feedName>`

Fetch one page of a named feed and render it as a table (or JSON).

semilayer feed view posts.discover --api-key sk_... --limit 5
semilayer feed view posts.discover --context @ctx.json --json
semilayer feed view posts.discover --cursor 'eyJ2IjoxLC...' --limit 10

Flag	Description
`--api-key <key>`	sk_ or pk_ key (required)
`--context <json>`	Inline JSON or `@path/to/file.json`
`--cursor <token>`	Cursor returned from a previous page
`--limit <n>`	pageSize override
`--json`	Output raw JSON instead of a table

`semilayer feed tail <lens.feedName>`

Stream feed.tick events as NDJSON to stdout. Ctrl+C to stop.

semilayer feed tail posts.discover --api-key sk_...
# → { "type": "tick", "name": "discover", "newCount": 3, "topChanged": false, "ts": "..." }
# → { "type": "tick", "name": "discover", "newCount": 1, "topChanged": false, "ts": "..." }

Useful for observability and shell pipelines:

semilayer feed tail posts.discover --api-key sk_... | jq 'select(.newCount > 5)'

`semilayer feed explain <lens.feedName>`

Per-record per-scorer breakdown. Requires an sk_ key — pk_ keys get a friendly client-side error before the request fires.

semilayer feed explain posts.discover --api-key sk_... --record 42 --context @ctx.json

  Record:  42
  Final score:  0.8614
  Rank:  3

  Per-scorer contributions:
  SCORER      WEIGHT  RAW     WEIGHTED
  similarity  0.55    0.50    0.2750
  recency     0.15    0.72    0.1080
  engagement  0.20    1.00    0.2000

Flag	Description
`--api-key <key>`	Service key (sk_) — pk_ rejected
`--record <id>`	Source row id (required)
`--context <json>`	Inline JSON or `@path/to/file.json`
`--json`	Output raw JSON instead of a table

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.