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

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

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 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