FLXBL CLI

The FLXBL CLI is the primary developer interface for local projects, CI, and agent-driven workflows. It manages schemas, data, relationships, API specs, auth settings, webhooks, and generated TypeScript clients.

Installation

# App-local install for generated clients
npm install -D @flxbl-dev/cli

# Global install for interactive use
npm install -g @flxbl-dev/cli

# Direct execution
npx @flxbl-dev/cli --help

Global Flags

Every command accepts the same auth, output, and automation flags.

flxbl --json --instance https://api.flxbl.dev --api-key "$FLXBL_API_KEY" <command>

# Global flags available on every command
-j, --json             Emit machine-readable JSON to stdout
-y, --yes              Skip confirmation prompts
-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

Environment Variables

Variable Purpose
FLXBL_INSTANCE_URL Default FLXBL API instance URL.
FLXBL_API_KEY API key for non-interactive authentication.
FLXBL_TOKEN_PATH Override the local credential store path.
NO_COLOR Disable ANSI colors for logs and tables.

Auth And Session

For a local shell, flxbl login is the easiest path. It opens browser-based OAuth through FLXBL Platform at https://platform.flxbl.dev and stores the resulting token. Use --api-key or FLXBL_API_KEY for non-interactive automation. 

# Easiest local auth: opens browser-based login through FLXBL Platform
flxbl login
flxbl login --instance https://api.flxbl.dev

# Optional email/password prompt
flxbl login --email

# Non-interactive auth for CI and agents
flxbl login --api-key "$FLXBL_API_KEY"

flxbl whoami --json
flxbl logout
flxbl logout --all

Project Setup

flxbl init
flxbl init --instance https://api.flxbl.dev --output-dir ./flxbl/_generated --yes

flxbl doctor
flxbl about --json
flxbl completion zsh

LLM Context

The context command is the fastest way to give a coding agent the current tenant, active schema, API endpoints, identity configuration, and command inventory. 

flxbl context
flxbl context --json
flxbl context --full --json
flxbl context --section schema --json
flxbl context --section commands --json
flxbl context --watch 5000 --json

Code Generation And Watch Mode

Generate typed SDK files from the active schema. Use Zod output when your app wants runtime input validation next to TypeScript types. 

flxbl generate
flxbl pull
flxbl generate --output ./src/flxbl
flxbl generate --format zod

# Watch schema changes and regenerate
flxbl dev
flxbl dev --json

Schema Management

flxbl schema show
flxbl schema show --format tree
flxbl schema show --json

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

flxbl schema export > schema.json
flxbl schema validate --file ./schema.json
cat schema.json | flxbl schema validate --stdin --json
flxbl schema diff ./schema.json
flxbl schema versions --json
flxbl schema migrate --file ./schema-v2.json --yes
flxbl schema migration-status <migrationId> --json
flxbl schema template
flxbl schema delete <schemaId> --yes

Data And Entities

flxbl data Product --limit 20
flxbl data Product --where '{"status":"active"}' --fields id,name --json

flxbl entity get Product prod_123 --json
flxbl entity list Product --where '{"status":"active"}' --fields id,name --limit 50 --json
flxbl entity list Product --search "contract renewal" --fields id,title,status --limit 25 --offset 0 --order-by createdAt --order-direction DESC --json
echo '{"name":"Widget","price":9.99}' | flxbl entity create Product --stdin --json
echo '{"price":12.50}' | flxbl entity patch Product prod_123 --stdin --json
flxbl entity delete Product prod_123 --yes --json

cat products.json | flxbl entity batch create Product --stdin --json

Relationships

flxbl relationship list Product node_abc BELONGS_TO --direction both --limit 10 --offset 0 --json
flxbl relationship create Product prod_1 BELONGS_TO cat_42 --properties '{"source":"import"}' --json
flxbl relationship update Product prod_1 BELONGS_TO cat_42 --properties '{"role":"owner"}' --json
flxbl relationship update-by-id Product prod_1 BELONGS_TO rel_789 --properties '{"role":"owner"}' --json
flxbl relationship delete Product prod_1 BELONGS_TO cat_42 --yes --json
flxbl relationship delete-by-id Product prod_1 BELONGS_TO rel_789 --yes --json
flxbl relationship delete-by-id Product prod_1 BELONGS_TO rel_789 --dry-run --json

Target-id commands mutate the relationship between a source node and a target node. By-id commands mutate the durable relationship edge id returned by relationship list responses, which is the right choice when multiple edges can connect the same nodes.

GraphQL, API Specs, And Vector Search

flxbl graphql "{ products { id name price } }" --json
echo '{"query":"{ products { id name } }"}' | flxbl graphql --stdin --json

flxbl api spec --json > openapi.json
flxbl api graphql-schema > schema.graphql

flxbl vector-search Document \
  --field embedding \
  --vector '[0.1,0.2,0.3]' \
  --top-k 5 \
  --json

Team, Roles, Access Keys, Webhooks, And Identity

flxbl team list --json
flxbl team invite alice@example.com --role <roleId>
flxbl team remove <userId> --yes

flxbl role list --json
flxbl role create Viewer --permissions read,list --json
flxbl role update <roleId> --permissions read,list,write --json
flxbl role assign <roleId> <userId>
flxbl role delete <roleId> --yes

flxbl access-key list --json
flxbl access-key create "CI bot" --scopes read,list,write --json
flxbl access-key revoke <keyId> --yes

flxbl webhook list --json
flxbl webhook create --url https://example.com/hooks/flxbl --events entity.created,entity.updated --schema Product --json
flxbl webhook update <id> --active false --json
flxbl webhook delete <id> --yes

flxbl identity show --json
flxbl identity update --min-password-length 12 --access-token-minutes 60 --json

Dry Run And Stdin

Mutating commands that accept request bodies support stdin payloads, and commands with explicit preview support expose --dry-run. This is useful for agents and CI because the CLI prints the request it would send without calling the backend. 

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

flxbl webhook delete <id> --dry-run --json
flxbl schema migrate --file ./schema-v2.json --dry-run --json

Exit Codes

Automation can branch on stable numeric exit codes.

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
8  rate limited
9  network error

Next Steps