LLM-Friendly CLI

FLXBL is designed to be driven from a normal shell. Coding agents can use the same CLI as humans: load tenant context, inspect schemas, generate typed clients, preview mutations, and execute approved changes through a stable command surface.

Why Agents Should Use The CLI

  • Stable JSON: --json emits machine-readable output.
  • Context bootstrap: flxbl context --full --json describes the tenant, schema, endpoints, identity config, and command inventory.
  • No temporary files required: --stdin accepts JSON payloads directly from the shell.
  • Safe previews: --dry-run --json shows the request without calling the backend.
  • Predictable recovery: documented exit codes distinguish auth, validation, rate limit, network, and breaking-change errors.

Session Bootstrap

In an interactive terminal, start with flxbl login. It opens browser-based authentication through FLXBL Platform at https://platform.flxbl.dev. For headless CI and agent loops, set credentials in the environment and load the full context once. Do not paste keys into prompts, source files, or generated docs. 

# Easiest local setup: opens browser-based login through FLXBL Platform
flxbl login

# Non-interactive sessions use environment variables
export FLXBL_INSTANCE_URL="https://api.flxbl.dev"
export FLXBL_API_KEY="flxbl_your_api_key"

flxbl doctor --json
flxbl context --full --json

Inspect Before Acting

Agents should inspect schema and API shape before guessing entity names, field names, relationships, or GraphQL operations. 

flxbl context --section schema --json
flxbl schema show --json
flxbl api spec --json > openapi.json
flxbl api graphql-schema > schema.graphql

Query Data Safely

Use JSON output for readbacks and keep filters explicit. Entity reads can combine filters, full-text search, field projection, pagination, and ordering. Relationship lists use direction plus offset pagination. 

flxbl entity list Product \
  --where '{"status":{"$eq":"active"}}' \
  --search "contract renewal" \
  --fields id,title,status \
  --limit 25 \
  --offset 0 \
  --order-by createdAt \
  --order-direction DESC \
  --json

flxbl relationship list Product node_abc BELONGS_TO \
  --direction out \
  --limit 10 \
  --offset 0 \
  --json

Generate Typed Clients

Use code generation after schema changes and before application code that depends on generated collection helpers. 

flxbl generate --output ./flxbl/_generated
flxbl generate --format zod
flxbl dev --json

Preview Mutations

Use dry runs before creating data, migrating schemas, deleting records, or changing webhooks. Add --yes only after destructive or breaking behavior has been approved. 

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

cat schema-v2.json | \
  flxbl schema migrate --stdin --dry-run --json

flxbl webhook delete wh_123 --dry-run --json

Pipe Payloads With Stdin

Prefer stdin for structured payloads in agent loops. It avoids brittle shell escaping and keeps JSON construction separate from command execution. 

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

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

cat webhook.json | \
  flxbl webhook create --stdin --json

Update Relationship Properties

Relationship property updates use an explicit --properties JSON object. Keep the payload small and request JSON output for agent parsing. 

flxbl relationship update Product node_abc BELONGS_TO node_category_xyz \
  --properties '{"role":"owner"}' \
  --json

Relationship edge IDs

When an agent needs to mutate a specific edge, list relationships first, capture the returned relationship id, then use the by-id command. Use --dry-run only on supported destructive commands such as relationship delete-by-id. 

# 1. List relationships and inspect the returned relationship id
flxbl relationship list Product prod_1 BELONGS_TO --direction out --json

# 2. Update the exact relationship edge by id
flxbl relationship update-by-id Product prod_1 BELONGS_TO rel_789 \
  --properties '{"role":"owner"}' \
  --json

# 3. Preview and execute destructive edge deletion
flxbl relationship delete-by-id Product prod_1 BELONGS_TO rel_789 --dry-run --json
flxbl relationship delete-by-id Product prod_1 BELONGS_TO rel_789 --yes --json

Use Exit Codes For Recovery

Treat non-zero exits as structured states, not generic failure. In JSON mode, error envelopes are written to stderr with a code, message, details, and exit code. 

case "$?" in
  0) echo "success" ;;
  2) echo "usage error: check command shape" ;;
  3|4) echo "auth problem: refresh credentials" ;;
  6) echo "validation error: inspect stderr JSON" ;;
  7) echo "breaking schema change: ask for approval before --yes" ;;
  8) echo "rate limited: back off and retry later" ;;
  9) echo "network error: retry if safe" ;;
esac

Agent Safety Rules

  • Never print environment files, token stores, API keys, or access tokens.
  • Use flxbl login for browser-based local authentication when an interactive terminal is available.
  • Prefer FLXBL_INSTANCE_URL and FLXBL_API_KEY for non-interactive sessions.
  • Run flxbl context --json or flxbl schema show --json before schema-dependent work.
  • Run --dry-run --json before supported mutating or destructive commands.
  • Use --yes only after the command and consequences are approved.
  • Regenerate clients after schema changes and run the consuming app's type checks.

Related Docs