Skip to main content

Quick Start Guide

This guide walks you through installing the SemanticFed CLI, connecting a source, modeling it, and running your first federated query.

Environment

All examples target production by default. To switch to local or alpha, set BURDENOFF_ENV=local or BURDENOFF_ENV=alpha. See Environment Selection for details.

Prerequisites​

  • A SemanticFed workspace (sign in at app.semanticfed.com)
  • Credentials for at least one data source (database, warehouse, lake, or API)
  • Node.js 24.11+ or Bun 1.3.14+

Step 1: Install the CLI​

npm install -g @semanticfed/cli
# or
bun add -g @semanticfed/cli

Step 2: Authenticate​

semanticfed auth login

This opens a browser for OAuth2 device-code approval. After login:

semanticfed auth status
semanticfed workspace list
semanticfed workspace set <workspace-id>

Step 3: Register a data source​

# Create a connector for a kind of source, then register a concrete source.
# Only the credential reference (secretRef) is stored — never the secret itself.
semanticfed source add \
  --connector postgres \
  --name "operational-pg" \
  --endpoint "postgres://db.internal:5432/app" \
  --secret-ref "kv://operational-pg" \
  --pushdown on

A connection probe records health and latency and moves the source to CONNECTED.

Step 4: Model your business​

Create a semantic model, add entities bound to the source, then define dimensions to slice by and metrics to measure. Publish the model to make it available to every consumer (DRAFT → PUBLISHED).

Step 5: Run your first federated query​

semanticfed semanticfed queries list
semanticfed semanticfed models list

Next Steps​

For help, contact our Support Team.