@flxbl-dev/cli

Developer CLI for FLXBL — manage schemas, entities, relationships, identities, and webhooks; generate typed TypeScript SDKs; and feed live tenant context to LLM agents.

@flxbl-dev/cli replaces the deprecated @flxbl-dev/mcp server. Every command is designed to work equally well from a human shell and from an LLM tool-calling loop: stable flags, JSON envelopes, stdin piping, exit codes, and a one-shot context bootstrap payload.

Install

# global
npm install -g @flxbl-dev/cli

# per-project (recommended when using the codegen)
npm install -D @flxbl-dev/cli

Requires Node.js >= 18.

Quick Start

flxbl login                   # authenticate
flxbl init                    # create flxbl.config.ts
flxbl doctor                  # verify local setup + backend reachability
flxbl context --json          # LLM bootstrap payload (tenant, schema, endpoints)
flxbl generate                # write typed SDK to ./flxbl/_generated

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

const db = createFlxblClient({
  instanceUrl: 'https://api.flxbl.dev',
  apiKey: process.env.FLXBL_API_KEY,
});

const users = await db.users.query({ where: { role: 'admin' } });
const post = await db.posts.create({ title: 'Hello', content: '...' });

// Available only on generated collections for entities with VECTOR fields.
const matches = await db.documents.vectorSearch({
  field: 'embedding',
  vector: embedding,
  topK: 10,
});

Global Flags

Available on every command:

| Flag | Description | | ---------------------- | -------------------------------------------------------- | | -j, --json | Emit machine-readable JSON envelope to stdout | | -y, --yes | Skip confirmation prompts (breaking migrations, deletes) | | -v, --verbose | Extra debug output to stderr | | -q, --quiet | Suppress non-essential output | | -i, --instance <url> | FLXBL instance URL | | -k, --api-key <key> | API key for authentication | | -t, --tenant <id> | Tenant ID |

Setting NO_COLOR=1 or piping to a non-TTY disables ANSI colors automatically.

Command Reference

Auth & Session

flxbl login [--email] [--api-key <key>] [--instance <url>]
flxbl logout [--instance <url>] [--all]
flxbl whoami

Project Setup

flxbl init [--instance <url>] [--output-dir <dir>] [--yes]
flxbl about                       # CLI version + build metadata
flxbl doctor                      # health checks: version, auth, backend, schema
flxbl completion <bash|zsh|fish>  # shell completion script

Wire up completions (zsh example):

echo 'eval "$(flxbl completion zsh)"' >> ~/.zshrc

LLM Context

flxbl context                              # compact snapshot (tenant, active schema, commands)
flxbl context --full --json                # include API endpoints + identity config
flxbl context --section schema             # single section: tenant | schema | api | identity | commands
flxbl context --watch 5000 --json          # NDJSON stream on change, every 5s

Load once per LLM session instead of injecting schema per turn.

Codegen & Watch

flxbl generate [--output <dir>] [--format interface|zod]
flxbl pull                                 # alias for generate
flxbl dev [--poll-interval <ms>]           # watch schema, regenerate on change
flxbl dev --json                           # NDJSON events for agent loops

--format zod generates Create<Entity>InputSchema and Update<Entity>InputSchema beside the inferred TypeScript input types. The generated files import zod, so projects that choose this format should install Zod in the consuming application:

npm install zod

import { CreateBonInputSchema } from './flxbl/_generated';

const parsed = CreateBonInputSchema.parse(formData);

Data Viewer

flxbl data <Entity> [--where <json>] [--fields <a,b,c>] [--limit <n>] [--format table|json]
flxbl vector-search <Entity> --field <name> --vector '[0.12,0.34,0.56]' [--json]

Schema

flxbl schema show [--format table|tree|json]
flxbl schema versions
flxbl schema export > schema.json
flxbl schema template [--id <templateId>]

flxbl schema create --file ./schema.json [--activate]
cat schema.json | flxbl schema create --stdin

flxbl schema migrate --file ./v2.json [--yes]         # --yes accepts breaking changes
flxbl schema migrate --status <migrationId>
flxbl schema migration-status <migrationId>

flxbl schema validate --file ./schema.json
flxbl schema diff <fromVersion> <toVersion>
flxbl schema delete <schemaId> [--yes]

Entities

flxbl entity get    <Type> <id>
flxbl entity list   <Type> [--where <json>] [--search <text>] [--fields <a,b>] [--limit <n>] [--traverse <json>]
flxbl entity create <Type> --data <json> | --stdin
flxbl entity update <Type> <id> --data <json> | --stdin       # full replace
flxbl entity patch  <Type> <id> --data <json> | --stdin       # partial update
flxbl entity delete <Type> <id> [--yes]
flxbl entity batch  <create|update|patch|delete> <Type> --items <json> | --stdin

flxbl entity list Product --search "contract renewal" --limit 25

Relationships

flxbl relationship list   <Type> <id> <REL> [--direction in|out|both] [--limit <n>] [--offset <n>]
flxbl relationship create <Type> <id> <REL> <targetId> [--properties <json>]
flxbl relationship update <Type> <id> <REL> <targetId> --properties <json>
flxbl relationship delete <Type> <id> <REL> <targetId> [--yes]
flxbl relationship update-by-id <Type> <id> <REL> <relationshipId> --properties <json>
flxbl relationship delete-by-id <Type> <id> <REL> <relationshipId> [--yes]

flxbl relationship list Product prod_1 BELONGS_TO --direction out --limit 10 --offset 20
flxbl relationship update Product prod_1 BELONGS_TO cat_1 --properties '{"role":"owner"}'
flxbl relationship update-by-id Product prod_1 BELONGS_TO rel_789 --properties '{"role":"owner"}'

Endpoint-based update/delete mutate by source id, relationship name, and target id. If parallel same-type edges can exist between the same two records, use the durable relationship id returned in relationship list/create responses with update-by-id or delete-by-id.

GraphQL & API Specs

flxbl graphql "<query>" [--variables <json>]
echo '{"query":"..."}' | flxbl graphql --stdin --json

flxbl api spec [--schema-id <id>] --json > openapi.json
flxbl api graphql-schema > schema.graphql

Team, Roles, Access Keys, Webhooks, Identity

flxbl team   list | invite <email> [--role <roleId>] | remove <userId>
flxbl role   list | create <name> --permissions <a,b> | update <id> | delete <id> | assign <roleId> <userId>
flxbl access-key list | create <name> --scopes <a,b> | revoke <id>
flxbl webhook list | create --url <u> --events <a,b> --schema <s> | update <id> | delete <id>
flxbl identity show
flxbl identity update [--min-password-length <n>] [--access-token-minutes <n>] [--refresh-token-days <n>]

Interactive role create and entity list wizards run when invoked in a TTY without arguments.

LLM-Friendly Conventions

The CLI is built to be driven by agents. Every mutating command follows the same contract:

--json — every command emits a stable JSON envelope on stdout. Errors emit { code, message, details?, exitCode } to stderr.

--stdin — any command that takes a --data, --file, or --items argument also accepts the payload on stdin, so agents don't need a filesystem:

echo '{"name":"Widget","price":9.99}' | flxbl entity create Product --stdin --json

--dry-run — supported by all mutating commands (entity, relationship, role, webhook, schema create|delete|migrate|validate, identity update, team invite|remove). Prints the request that would be sent (method, path, body) and exits 0 without calling the API. No backend support required.

flxbl entity create Product --data '{"name":"X"}' --dry-run --json

--yes — non-interactive acceptance for destructive actions and breaking schema migrations.

Exit codes — stable, numeric, documented:

| Code | Meaning | | ---- | ------------------------------------------------------ | | 0 | Success | | 1 | General error | | 2 | Usage / invalid arguments | | 3 | Authentication required | | 4 | Authentication expired | | 5 | Resource not found | | 6 | Validation error | | 7 | Breaking schema change (re-run with --yes to accept) | | 8 | Rate limited | | 9 | Network error |

Configuration

Create flxbl.config.ts at your project root (or run flxbl init):

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,
    includeQueryTypes: true,
  },
  dev: {
    pollInterval: 3000,
  },
} satisfies FlxblConfig;

Resolved by walking up from the current directory (like tsconfig.json). Supports .ts, .js, .mjs.

Authentication Resolution

Auth is resolved in this order:

1. CLI flag (--api-key, --instance)
2. Environment variables (FLXBL_API_KEY, FLXBL_INSTANCE_URL)
3. Project config (flxbl.config.ts — for instanceUrl only, including login)
4. Stored credentials (~/.flxbl/tokens.json, or FLXBL_TOKEN_PATH when set)

Environment Variables

| Variable | Description | | -------------------- | --------------------------------------------------------------- | | FLXBL_INSTANCE_URL | Default instance URL | | FLXBL_API_KEY | API key for non-interactive auth | | FLXBL_TOKEN_PATH | Override token store location (default: ~/.flxbl/tokens.json) | | NO_COLOR | Set to 1 to disable ANSI color output |

Generated Output

Running flxbl generate produces the following in your output directory:

| File | Contents | | ------------------ | ------------------------------------------------------ | | entities.ts | TypeScript interfaces for each entity | | create-dtos.ts | CreateXInput / UpdateXInput DTOs | | enums.ts | Union types for ENUM fields | | relationships.ts | Relationship name union + definition interfaces | | query-types.ts | Per-entity Where, query response, and vector aliases | | client.ts | TypedFlxblClient with per-entity collections | | index.ts | Barrel re-export | | _metadata.json | Generation timestamp, schema version |

Add flxbl/_generated/ to .gitignore — these files are regenerated from the schema.

Generated collections include query() and the CRUD-style findMany() alias for the Dynamic REST query endpoint. Collections for entities with one or more VECTOR fields also include vectorSearch() with field constrained to that entity's VECTOR field names.

Requires @flxbl-dev/client as a production dependency for the generated client runtime.

Replacing @flxbl-dev/mcp

The MCP server is deprecated in favor of this CLI. See MCP-TO-CLI-MIGRATION.md and ADR-001 for rationale and a tool-by-tool mapping.

License

MIT