FFDB Docs
FFDBInstallOpen portal
SDKs and tools›CLI

CLI

Manage platform credentials, projects, data, policies, storage, email, and operations with the ffdb binary.

Operate FFDB from the terminal

The packaged CLI manages platform credentials, organizations, projects, migrations, policies, storage, operations, scaffolding, and type generation.

It gives operators a scriptable public surface without direct access to PostgreSQL or project files.

Use it from an operator workstation or trusted automation environment.

Requirements for CLI

  • Prerequisite — The verified @ffdb/cli SDK package or packaged ffdb executable.
  • Prerequisite — Network access to a ready FFDB origin and an owner-only configuration location.
  • Required value — API URL, platform login or scoped project developer key, organization/project IDs, output mode, and confirmation policy.
  • Required value — FFDB_CONFIG when the default credential path is unsuitable.

Install the CLI package

Install @ffdb/cli at the exact server version in a trusted operator environment. Use the checksum-listed release tarball for verified offline installation.

Terminalsh
npm view @ffdb/cli dist-tags --json
npm install --global @ffdb/cli@0.3.14
ffdb --help

Runtime, output, and errors

@ffdb/cli requires Node.js 24 or newer. Global options are parsed before the command: --url, --project, --key, --config, and --json. With --json, successful values are serialized for automation; without it, the CLI prints a human-readable projection. Unknown commands, invalid or missing arguments, missing credentials, declined destructive confirmations, file errors, and FFDB API errors exit non-zero and write a bounded message to stderr.

  • Supported environment variables: FFDB_BOOTSTRAP_TOKEN, FFDB_COMMERCE_STRIPE_SECRET_KEY, FFDB_COMMERCE_STRIPE_WEBHOOK_SECRET, FFDB_CONFIG, FFDB_DEVELOPER_KEY, FFDB_DEVELOPER_SESSION, FFDB_INSTANCE_STRIPE_CONNECT_SECRET_KEY, FFDB_INSTANCE_STRIPE_CONNECT_WEBHOOK_SECRET, FFDB_INSTANCE_STRIPE_SECRET_KEY, FFDB_INSTANCE_STRIPE_WEBHOOK_SECRET, FFDB_PASSWORD, FFDB_PROJECT_ID, FFDB_URL.
  • Credential precedence: explicit global flags, then environment variables, then the owner-only credential file.
  • Commands marked [--yes] prompt before destructive work unless automation supplies that flag.
  • JSON-file arguments are parsed before the request; invalid JSON fails locally without mutating the server.
Automationsh
ffdb --url https://data.example.com --json health
FFDB_PASSWORD="$FFDB_PASSWORD" ffdb login admin@example.com
ffdb --json project list "$FFDB_ORGANIZATION_ID"

CLI: Usage

  • ffdb [--url URL] [--project ID] [--key KEY] [--config PATH] [--json] <command>
  • ffdb help <topic> | ffdb help all
  • Destructive commands prompt interactively; pass --yes for automation.

CLI: Project setup

  • init <directory> [browser|react|node] — scaffold a starter without embedding secrets
  • generate [output-path] — generate TypeScript types from the live schema
  • generate --out <path> — choose the generated TypeScript output path
  • types generate [--out <path>] — alias for generate

CLI: Credential lifecycle

  • login [email] — securely prompt for missing credentials; FFDB_PASSWORD supports automation
  • logout — revoke the current session and remove its local credential
  • project link <project-id> — persist the active project for future commands

CLI: Instance lifecycle

  • instance setup-status — inspect public bootstrap availability
  • instance bootstrap [owner-email] — create the first owner using secure credentials
  • instance status — inspect instance mode, policy, billing, and capabilities
  • instance setup|configure <private|team> <policy> — configure a non-billing instance
  • instance setup|configure byo <policy> — configure operator-owned Stripe credentials
  • instance setup|configure connect <policy> <country> <email> <return-url> <refresh-url>
  • instance policy set <owner_only|authenticated|invitation_only>
  • instance connect onboarding <return-url> <refresh-url>
  • instance connect refresh — refresh Stripe Connect readiness
  • instance admins list — list delegated instance administrators
  • instance admins grant <user-id> — grant instance administration
  • instance admins revoke <user-id> [--yes] — revoke instance administration
  • instance organizations [limit] [offset] — inspect organizations across the instance
  • instance users [limit] [offset] — inspect users across the instance
  • instance org-disable|org-enable <org-id> [--yes]
  • instance user-disable|user-enable <user-id> [--yes]
  • instance exemptions list — list billing exemptions
  • instance exemptions grant <org-id> <json-file> — grant a documented exemption
  • instance exemptions revoke <org-id> [--yes] — remove an exemption
  • instance plans list — list instance plan definitions
  • instance plans put <free|pay_as_you_go|pro> <json-file> — create or update a plan
  • instance plans retire <free|pay_as_you_go|pro> [--yes] — retire a plan
  • Bootstrap reads FFDB_BOOTSTRAP_TOKEN and FFDB_PASSWORD without printing or storing them.
  • BYO setup reads FFDB_INSTANCE_STRIPE_SECRET_KEY and FFDB_INSTANCE_STRIPE_WEBHOOK_SECRET.

CLI: Platform and project

  • org list — list organizations available to the signed-in developer
  • org create <name> <slug> — create an organization
  • org members <org-id> — list organization membership
  • org invite <org-id> <email> <role> — invite an owner, admin, developer, or viewer
  • org member-role <org-id> <user-id> <role> — update a member role
  • org member-remove <org-id> <user-id> [--yes] — remove a member
  • project list <org-id> — list projects in an organization
  • project create <org-id> <name> <slug> [region] — create a project
  • billing status <org-id> — inspect subscription status
  • billing checkout <org-id> <pay_as_you_go|pro> — start checkout
  • billing portal <org-id> — open subscription management
  • billing invoices <org-id> — list invoices
  • billing usage <org-id> — inspect billable usage
  • commerce status — inspect the active project's commerce account
  • commerce refresh — refresh provider capabilities
  • commerce configure-byo — configure Stripe using secure environment variables
  • commerce disconnect --yes — disconnect the project's commerce account
  • commerce connect <country> <email> <return-url> <refresh-url>
  • commerce products [--all] — list products
  • commerce product-create <json> | commerce product-archive <id>
  • commerce prices [--all] — list prices
  • commerce price-create <json> | commerce price-retire <id>
  • commerce orders | commerce payments | commerce subscriptions
  • commerce refund <json> | commerce cancel <subscription-id> [--now]
  • commerce portal <individual|team|organization> <subject-id> <return-url>
  • commerce entitlements <individual|team|organization> <subject-id>
  • commerce fulfill <order-id> <unfulfilled|processing|fulfilled|canceled> [note]
  • api-key list — list developer API keys
  • api-key create <name> <scope,...> — create a scoped developer key
  • api-key revoke <id> [--yes] — revoke a developer key

CLI: Database workflows

  • sql <statement> — execute an inline SQL statement
  • sql --file <path> — execute SQL from a file
  • seed <path> — apply a seed file
  • schema — inspect the current schema snapshot
  • policies — inspect row-level security policies
  • migration create <name> — create an up/down migration file
  • migration status — inspect applied migration history
  • migration apply <path> — apply an idempotent migration
  • migration rollback <id> [--yes] — roll back an applied migration

CLI: Auth, storage, and email

  • auth settings — inspect project authentication settings
  • auth set <json> — update authentication settings from a JSON file
  • auth users — list project authentication users
  • auth disable <id> [--yes] — disable an authentication user
  • auth enable <id> — enable an authentication user
  • storage buckets — list object-storage buckets
  • storage create-bucket <name> [--versioning] — create a private bucket
  • storage cleanup — clean expired upload reservations
  • email templates — list project email templates
  • email import-artifact <json> — import a compiled email artifact
  • email publish <kind> <version> — publish a template version

CLI: Operations

  • logs [limit] — read recent project logs
  • backup list — list project backups
  • backup create — create a project backup
  • backup restore <id> [--yes] — replace project data from a backup
  • backup integrity — check project database integrity
  • health — check API liveness
  • dev — check liveness, readiness, API URL, and active project

Credential resolution

The CLI resolves explicit flags first, then environment variables, then its owner-only credential file. Platform login and project developer keys remain separate.

Terminalsh
FFDB_PASSWORD="$FFDB_PASSWORD" ffdb --url https://ffdb.example.com login developer@example.com
ffdb project link "$FFDB_PROJECT_ID"
ffdb schema --json
ffdb policies --json
ffdb health

Scaffold and generate schema types

init accepts browser, react, or node and refuses to overwrite an existing generated file. generate reads the linked project's live /schema contract and atomically writes conservative TypeScript interfaces.

  • BLOB columns use BlobValue from @ffdb/client.
  • Integer, real, date, and timestamp declarations map to number.
  • Nullable columns include null.
  • Unknown or unrecoverable SQLite declarations remain unknown.
Terminalsh
ffdb init ../notes-app react
ffdb generate --out ../notes-app/src/ffdb.types.ts

Billing and project commerce

Platform billing commands take an explicit organization ID. Project commerce uses the project currently linked in the CLI configuration and exposes complete provider setup, catalog, Checkout, order, refund, subscription, entitlement, and fulfillment workflows.

  • Platform Checkout and Portal require Stripe configured by the instance owner.
  • A returned provider redirect is not proof that billing state changed; re-read billing status after verified webhook processing.
  • Project commerce is configured independently per project with encrypted BYO Stripe credentials or optional Connect direct charges.
  • Run ffdb commerce --help for BYO/Connect setup, prices, Checkout-adjacent administration, refunds, entitlements, cancellation, and paid fulfillment commands.
Terminalsh
ffdb billing status "$FFDB_ORGANIZATION_ID"
ffdb billing checkout "$FFDB_ORGANIZATION_ID" pay_as_you_go
ffdb billing checkout "$FFDB_ORGANIZATION_ID" pro
ffdb billing portal "$FFDB_ORGANIZATION_ID"
ffdb commerce status
ffdb commerce products
ffdb commerce orders
ffdb commerce subscriptions

CLI module functions

  • export function parseArguments(argv: readonly string[]): ParsedArguments
  • export function required(value: string | undefined, label: string): string
  • export function parsePaidBillingTier(value: string | undefined): Exclude<PlatformBillingTier, "free">
  • export function defaultCredentialPath(): string
  • export function parseProjectTemplate(value: string | undefined): ProjectTemplate
  • export async function scaffoldProject( targetDirectory: string, template: ProjectTemplate, options: { readonly templateRoot?: string } = {},): Promise<ScaffoldResult>
  • export async function executeInstanceCommand( client: FFDBClient, action: string | undefined, args: readonly string[], environment: InstanceCommandEnvironment = process.env,): Promise<unknown>
  • export function instanceConfiguration( args: readonly string[], environment: InstanceCommandEnvironment = process.env,): CompleteInstanceSetupRequest
  • export function parseOrganizationPolicy(value: string | undefined): OrganizationCreationPolicy
  • export function parseMigration(source: string, filename: string, createdAtMs: number): MigrationSpec
  • export async function loadMigration(path: string, createdAtMs = Date.now()): Promise<MigrationSpec>
  • export async function confirmDestructive( message: string, yes: boolean, io: ConfirmationIO = { input: process.stdin, output: process.stdout },): Promise<void>
  • export function migrationIdempotencyKey(migration: MigrationSpec): string
  • export function generateDatabaseTypes(schema: SchemaSnapshot): string
  • export async function writeDatabaseTypes(schema: SchemaSnapshot, outputPath: string): Promise<string>

CLI module interfaces and types

  • export interface CliCredentials { readonly baseUrl: string; readonly projectId?: string; readonly developerKey?: string; readonly developerSessionToken?: string; readonly developerEmail?: string; readonly developerUserId?: string; readonly developerSessionExpiresAtMs?: number; }
  • export interface ConfirmationIO { readonly input: Readable & { readonly isTTY?: boolean }; readonly output: Writable & { readonly isTTY?: boolean }; }
  • export interface CredentialStore { load(): Promise<CliCredentials | null>; save(credentials: CliCredentials): Promise<void>; clear(): Promise<void>; }
  • export type InstanceCommandEnvironment = Readonly<Record<string, string | undefined>>;
  • export interface ParsedArguments { readonly options: ParsedGlobalOptions; readonly command: readonly string[]; }
  • export interface ParsedGlobalOptions { readonly baseUrl?: string; readonly projectId?: string; readonly developerKey?: string; readonly configPath?: string; readonly json: boolean; }
  • export type ProjectTemplate = "browser" | "node" | "react";
  • export interface ScaffoldResult { readonly directory: string; readonly files: readonly string[]; readonly dependencies: readonly string[]; }

CLI module: FileCredentialStore

  • constructor(readonly path = defaultCredentialPath())
  • async load(): Promise<CliCredentials | null>
  • async save(credentials: CliCredentials): Promise<void>
  • async clear(): Promise<void>

Crawler-friendly CLI reference

The same shipped command and programmatic-module reference is available as static Markdown at /docs/reference/cli.md. It covers the public executable syntax and every export from the @ffdb/cli package root.

Automation

  • Use --json for machine-readable output.
  • Pass --yes only when an automation has already resolved a destructive target.
  • The CLI does not print stored credentials; newly issued key secrets are returned once by the server.
  • FFDB_CONFIG can choose an alternate credential file.

CLI workflow

  • 1. Install the packaged CLI and verify ffdb --help.
  • 2. Log in for platform management or link a project developer key.
  • 3. Run a read-only health/schema command first.
  • 4. Apply the intended migration or management command.
  • 5. Use --json and explicit confirmation behavior in automation.

Verify cli

The command returns stable human or JSON output and stores credentials only in the protected configured location.

Troubleshoot cli

  • The CLI resolves the wrong project — pass an explicit target and inspect configuration before mutation.
  • Automation waits for confirmation — resolve the target first, then use --yes only for that reviewed action.

Continue from CLI

  • Scaffold the application runtime.
  • Generate and commit schema types.