SemiLayerDocs

Quickstart

Get SemiLayer running in under 5 minutes. You'll connect a database, push a lens, and fire your first call through the Beam client.

ℹ️

Prerequisites: Node.js 18+, a database you can read from, and a SemiLayer account. No account yet? Sign up at console.semilayer.com.

ℹ️

Prefer to let an agent do it? Connect Claude Desktop, Cursor, or any MCP-aware agent to https://mcp.semilayer.com/mcp and describe your lens in plain English — the agent handles the config, dry-runs the change, and shows you a diff before anything commits. See MCP → for the 30-second setup.

1. Install the CLI

npm install -g @semilayer/cli

semilayer --version

2. Set up your project

Log in

semilayer login

A browser window opens; sign in and authorize the CLI. The token is stored locally and every subsequent command is authenticated.

Pick a context

semilayer init

Select or create an Organization, Project, and Environment. The choice is written to .semilayerrc so future commands know where to operate.

Connect a source

Fastest path: Quick Connect in the Console (console.semilayer.com → your org → Quick Connect). Pick a bridge, paste credentials (or point at a runner for private networks), pick a table, and it exports a matching sl.config.ts for you.

Prefer the CLI?

semilayer sources connect \
  --name main-db \
  --bridge @semilayer/bridge-postgres \
  --url "postgresql://user:pass@host:5432/mydb"

See Connect a Source for every connection mode including airgap.

3. Declare a lens and push

Open sl.config.ts (Quick Connect wrote one for you; otherwise create one). Add a lens over the table you want intelligence on:

import { defineConfig } from '@semilayer/core'

export default defineConfig({
  stack: 'my-app',
  sources: {
    'main-db': { bridge: '@semilayer/bridge-postgres' },
  },
  lenses: {
    products: {
      source: 'main-db',
      table: 'public.products',
      fields: {
        id:          { type: 'number',  primaryKey: true },
        name:        { type: 'text',    searchable: { weight: 2 } },
        description: { type: 'text',    searchable: true },
        category:    { type: 'enum',    values: ['footwear', 'apparel', 'accessories'] },
        price:       { type: 'number' },
      },
      grants: { search: 'public', similar: 'public' },
    },
  },
})
ℹ️

searchable is opt-in — only fields with searchable: true (or { weight: N }) are embedded. price and category get returned in results but don't influence ranking. See Fields & weights.

Push and start ingesting:

semilayer push --resume-ingest
semilayer status
# products  indexing  1,247 / 3,500  35%  ~2m remaining

When status reaches ready, queries are live.

4. Generate Beam, make your first call

semilayer generate

This writes a fully-typed client to ./semilayer/. Every lens in your config becomes a property on the beam instance:

searchproducts
products: {
  source: 'main-db',
  table: 'public.products',
  fields: {
    id:          { type: 'number',  primaryKey: true },
    name:        { type: 'text',    searchable: { weight: 2 } },
    description: { type: 'text',    searchable: true },
    category:    { type: 'enum',    values: ['footwear', 'apparel', 'accessories'] },
    price:       { type: 'number' },
  },
  grants: { search: 'public', similar: 'public' },
}

Flip Config between JSON and the Console lens editor view, Explorer for a live-looking result table, Call between Client / HTTP / WebSocket / cURL. This is the same lens, shown four ways.

What's next?

  • Concepts — the mental model: orgs, projects, lenses, operations, Beam
  • Search — go deep on the search operation: fields, filters, modes, recipes
  • Feeds — ranked, paginated, live-updating streams (the feed operation)
  • Auth & RBAC — API key types, access rules, per-user scoping
  • HTTP & WebSocket — write a client in any language