Lore

Core workflow

1. Get context before acting

Always start by understanding the schema and knowledge:

# What tables exist?
lore schema

# What does Lore know about a specific table?
lore context customers

Context includes: schema metadata, semantic knowledge, query patterns, corrections, and rules. Read context before querying to avoid mistakes other agents already made.

2. Read and write data (structured CRUD)

For simple operations, use the structured CRUD commands — no SQL needed:

# Read
lore get customers cust_100                            # single record by ID
lore list customers --where status=active --limit 10   # filtered list
lore list customers --order created_at:desc            # sorted
lore list customers --columns name,email               # select columns
lore count customers --where status=active             # count matching rows

# Write
lore create customers name="Acme Corp" email="[email protected]"
lore update customers cust_100 status=churned --desc "Customer churned"
lore delete customers cust_100 --desc "Duplicate entry"

Filter operators for --where: =, !=, >, >=, <, <=, LIKE, IS NULL, IS NOT NULL. Multiple --where flags are AND'd. For complex queries (JOINs, OR, IN, subqueries), use lore query with raw SQL.

Pagination: --limit N (default 50, max 1000) and --offset N. The response includes total count.

Auto-generated IDs: When creating a record without specifying an ID, a ULID is auto-generated (e.g., cust_01ARZ3NDEKTSV4RRFFQ69G5FAV).

3. Query and mutate (raw SQL)

For complex operations beyond simple CRUD, use raw SQL:

# Read-only SQL
lore query "SELECT stage, COUNT(*), SUM(value) FROM deals GROUP BY stage"

# Governed mutations
lore mutate "INSERT INTO customers (id, name, email) VALUES ('cust_100', 'Acme Corp', '[email protected]')" \
  --desc "Add new customer Acme Corp"

The query response includes knowledgeUsed (what Lore consulted) and learningHint (suggestions for improvement).

Governance enforces:

• Only INSERT/UPDATE/DELETE (no DDL)
• System tables blocked
• Access policies checked

4. Propose schema changes

Never run DDL directly. Think carefully about data structure before proposing — a well-designed schema keeps the org's data coherent and queryable. See Schema Design Guidelines for naming conventions, column types, and common mistakes.

lore schema propose \
  "CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL, status TEXT DEFAULT 'open', created_at TEXT NOT NULL)" \
  --reason "Task tracking for project management. Status values: open, in_progress, done."

Check status: lore pending

Approving/rejecting proposals requires explicit human confirmation:

lore approve <id> --approved-by-human
lore reject <id> --reason "..." --approved-by-human

The --approved-by-human flag is required. If you omit it, the CLI will remind you to confirm with the user first. Never pass this flag without the human explicitly agreeing.

6. Contribute knowledge

# Semantic: what data means
lore learn semantic "amount is stored in cents, divide by 100 for display" --scope orders

# Correction: fix a misunderstanding
lore learn correction "status=lead means prospect, not existing customer" --scope customers

# Pattern: a useful query
lore learn pattern "SELECT stage, COUNT(*), SUM(value) FROM deals GROUP BY stage" --scope deals

7. Custom domains

Standalone apps can be served on custom domains (e.g., dashboard.acme.com) instead of the default path. Setup: register domain → create CNAME to standalone.thelore.dev → verify. CF4SaaS handles TLS automatically.

lore domain add dashboard.acme.com --app my-app  # register
# → create CNAME: dashboard.acme.com → standalone.thelore.dev
lore domain verify <id>                           # activate after DNS propagates
lore domains                                      # list all
lore domain remove <id>                           # remove

See Standalone Apps — Custom Domains for the full setup guide, routing details, TLS lifecycle, troubleshooting, and API reference.

8. Import CSV data

Import bulk data from CSV files into existing tables. Ideal for ETL jobs, seed data, and migrations from external systems.

# Basic import
lore import customers ./customers.csv

# Validate without inserting (dry run)
lore import customers ./customers.csv --dry-run

# Abort on first error (default: skip bad rows)
lore import customers ./customers.csv --on-error abort

Features:

• Header normalization — "Customer Name" → customer_name automatically
• Auto-generated IDs — if the table has an id column and the CSV omits it, ULIDs are generated
• Type coercion — numbers, booleans, and nulls are inferred from column types
• Error modes — skip (default) imports good rows and reports bad ones; abort stops on first error
• No approval queue — imports bypass the bulk mutation threshold (access policies still enforced)

MCP:

{
  "tool": "import",
  "arguments": {
    "table": "customers",
    "csv": "name,email,segment\nAcme,[email protected],enterprise\n...",
    "options": { "onError": "skip", "dryRun": false }
  }
}

Limits: 10,000 rows per call, ~10 MB. For larger datasets, split into multiple calls.

9. Export database

Export the org database as a SQL dump (admin or owner required):

# Download to current directory (filename includes org slug and date)
lore org export

# Download to a specific path
lore org export --output ./backups/my-org.sql

Restore is owner-only and must be done through the web UI (Settings > Organization > Data) for safety. The restore flow requires typing the org name to confirm, validates the dump contains required system tables, and runs pending migrations after restore.

10. Manage views

# List all saved views
lore views

# Create a list view (auto-generates spec from table schema)
lore views create --name "Active Customers" --for customers

# Create a record view (server-side generation with FK detection)
lore views create --name "Customer Detail" --for customers --type record

# Create other view types (board, dashboard, chart — all use server-side generation)
lore views create --name "Task Board" --for tasks --type board

# Create a view with a custom spec file (supports commands for Cmd+K palette)
lore views create --name "Deals (with actions)" --for deals --spec ./spec.json

# Delete a view
lore views delete <view-id>

# Generate a ViewSpec on the fly without saving (ad-hoc browsing)
# Via API: GET /v1/views/generate?table=<tableName>&hint=<type>
# Hint values: table, board, dashboard, chart, record

See ViewSpec Reference for the full spec format — view types, sections, actions, toolbar, computed fields, 1:many relations, and examples.

Rules

1. Always get context first — lore context <table> before querying
2. Never bypass governance — schema changes go through lore schema propose, not raw DDL
3. Use parameterized queries — never interpolate untrusted values
4. Contribute what you learn — patterns, corrections, semantics
5. Check past feedback — before proposing schema changes, check if similar proposals were rejected

Reference docs

• API Reference — full REST endpoint list, request/response examples
• Governance Model — access policies, approval workflow, audit trail
• Knowledge System — query-learn loop, knowledge types, passive inference
• Schema Design — naming conventions, column types, proposal guidelines
• ViewSpec Reference — view types, sections, actions, toolbar, computed fields, 1:many relations
• Standalone Apps — standalone HTML apps with auth modes (internal, external, public)