FLXBL CLI

Generate typed SDKs, manage schemas, and query data from your terminal.

Installation

# Install globally
npm install -g @flxbl-dev/cli

# Or run directly with npx
npx @flxbl-dev/cli

Authentication

Authenticate with your FLXBL instance using interactive login or an API key. Credentials are stored securely and persist across sessions.

# Interactive login (prompts for instance URL, email, password)
flxbl login

# Login with API key
flxbl login --api-key flxbl_your_api_key --instance https://api.flxbl.dev

# Check current session
flxbl whoami

# Logout
flxbl logout

# Logout from all instances
flxbl logout --all

Command	Description
`flxbl login`	Interactive login (email/password) or `--api-key` for key-based auth
`flxbl logout`	Remove stored credentials (`--all` for all instances)
`flxbl whoami`	Display current user, tenant, and auth method

Project Setup

Initialize a FLXBL project in your repository. This creates a flxbl.config.ts file with your instance URL and code generation settings.

# Initialize a FLXBL project (interactive)
flxbl init

# Or with flags
flxbl init --instance https://api.flxbl.dev --output-dir ./flxbl/_generated

Configuration File

import type { FlxblConfig } from '@flxbl-dev/cli';

export default {
  instanceUrl: 'https://api.flxbl.dev',
  outputDir: './flxbl/_generated',
  codegen: {
    format: 'interface',           // 'interface' or 'zod'
    includeRelationships: true,    // Generate relationship types
    includeQueryTypes: true,       // Generate query option helpers
  },
  dev: {
    pollInterval: 3000,            // Schema poll interval in ms
  },
} satisfies FlxblConfig;

Option	Default	Description
`instanceUrl`	—	Your FLXBL instance URL (required)
`outputDir`	`./flxbl/_generated`	Directory for generated SDK files
`codegen.format`	`interface`	`interface` for TypeScript interfaces, `zod` for Zod schemas
`codegen.includeRelationships`	`true`	Generate relationship type helpers
`codegen.includeQueryTypes`	`true`	Generate typed query option helpers
`dev.pollInterval`	`3000`	Schema change polling interval in milliseconds

Code Generation

Generate a typed TypeScript SDK from your active schema. The generated client includes entity types, create/update inputs, and a typed FlxblClient with collection accessors for every entity.

# Generate typed SDK from your active schema
flxbl generate

# Or use the alias
flxbl pull

# With options
flxbl generate --output ./src/flxbl --format zod
flxbl generate --instance https://api.flxbl.dev --api-key flxbl_xxx

Generated Output

# Generated files
flxbl/_generated/
├── index.ts              # Main export
├── types.ts              # Entity interfaces (or Zod schemas)
├── client.ts             # Typed FlxblClient with collection accessors
├── relationships.ts      # Relationship type helpers
└── query-types.ts        # Query option helpers

# Usage
import { createFlxblClient } from './flxbl/_generated';

const client = createFlxblClient({
  instanceUrl: 'https://api.flxbl.dev',
  apiKey: 'flxbl_xxx',
});

// Fully typed — autocomplete on fields, filters, etc.
const products = await client.Product.findMany({
  where: { price: { $lte: 100 } },
  orderBy: 'name',
});

Tip: Add flxbl/_generated to your .gitignore and run flxbl generate in your CI pipeline or as a post-install script.

Watch Mode

Start watch mode to auto-regenerate the SDK whenever your schema changes. The CLI polls your instance for schema version changes and regenerates automatically.

# Watch mode — auto-regenerate on schema changes
flxbl dev

# With custom poll interval
flxbl dev --poll-interval 5000

Data Explorer

Query and display entity data directly in your terminal. Supports filtering, field selection, and table or JSON output.

# Query entity data
flxbl data Product --limit 50

# With filters
flxbl data Product --where '{"status":"active"}' --fields name,price

# JSON output
flxbl data Order --format json

# All options
flxbl data <entity> [options]
  -l, --limit <n>       Max records (default: 20)
  -w, --where <json>    Filter conditions as JSON
  -f, --fields <list>   Comma-separated fields
  --format <format>     table (default) or json

Vector Search

Perform vector similarity search on entities with VECTOR fields. Provide the query vector as a JSON array or as a path to a .json file.

# Vector similarity search
flxbl vector-search Document --field embedding --vector '[0.1,0.2,0.3,...]' --top-k 5

# Vector from a JSON file
flxbl vector-search Document --field embedding --vector ./query-vector.json --top-k 10

# With filters and field selection
flxbl vector-search Article \
  --field embedding \
  --vector '[0.1,0.2,...]' \
  --where '{"lang":"en"}' \
  --fields title,summary \
  --format json

# All options
flxbl vector-search <entity> [options]
  --field <name>        VECTOR field to search (required)
  --vector <json>       Query vector as JSON array or file path (required)
  --top-k <n>           Max results, 1-100 (default: 10)
  -w, --where <json>    Filter conditions as JSON
  -f, --fields <list>   Comma-separated fields
  --format <format>     table (default) or json

Schema Management

View, create, export, and manage schema versions from the command line.

View Schema

# Show active schema
flxbl schema

# Different formats
flxbl schema show --format table    # Tabular view (default)
flxbl schema show --format tree     # ASCII tree
flxbl schema show --format json     # Full JSON

Create Schema

Create a new schema interactively or import from a JSON file. The interactive wizard guides you through entity creation, field types, and relationship setup.

# Interactive schema creation
flxbl schema create

# Import from JSON file
flxbl schema create --file schema.json

# Create and auto-activate
flxbl schema create --file schema.json --activate

Export, Versions & Migrations

# Export schema to JSON (importable format)
flxbl schema export -o schema.json
flxbl schema export --schema-id abc123

# List schema versions
flxbl schema versions

# Check migration status
flxbl schema migrate <migrationId>

# Delete a schema
flxbl schema delete <schemaId>
flxbl schema delete <schemaId> --force

Subcommand	Description
`schema show`	Display active schema (table, tree, or JSON)
`schema create`	Create a new schema (interactive or from file)
`schema export`	Export schema to clean JSON (importable format)
`schema versions`	List all schema versions with status
`schema migrate`	Check migration status for a schema version
`schema delete`	Delete a schema by ID (`--force` to skip confirmation)

Environment Variables

The CLI checks these environment variables as fallbacks when flags or config are not provided:

Variable	Description
`FLXBL_INSTANCE_URL`	FLXBL instance URL (fallback for `--instance` and config)
`FLXBL_API_KEY`	API key for authentication (fallback for `--api-key`)

Next Steps

SDK - Use the generated client in your application
Schema Design - Learn about field types and relationships
API Reference - Complete REST and GraphQL documentation
Query DSL - Deep dive into filter operators