CLI

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.

npm view @ffdb/cli dist-tags --json
npm install --global @ffdb/cli@0.3.0
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.

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>
• Destructive commands prompt interactively; pass --yes for automation.

CLI: Project setup

• init <directory> [browser|react|node]
• generate [output-path] | generate --out <path> | types generate [--out <path>]

CLI: Credential lifecycle

• login <email> | logout | project link <project-id>

CLI: Instance lifecycle

• instance setup-status | instance bootstrap <owner-email> | instance status
• bootstrap reads FFDB_BOOTSTRAP_TOKEN and FFDB_PASSWORD without printing them
• instance setup|configure <private|team> <owner_only|authenticated|invitation_only>
• instance setup|configure byo <policy> # reads FFDB_INSTANCE_STRIPE_SECRET_KEY and FFDB_INSTANCE_STRIPE_WEBHOOK_SECRET
• 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
• instance admins list | instance admins grant <user-id> | instance admins revoke <user-id> [--yes]
• instance organizations [limit] [offset] | instance users [limit] [offset]
• instance org-disable|org-enable <org-id> [--yes]
• instance user-disable|user-enable <user-id> [--yes]
• instance exemptions list | instance exemptions grant <org-id> <json-file>
• instance exemptions revoke <org-id> [--yes]
• instance plans list | instance plans put <free|pay_as_you_go|pro> <json-file>
• instance plans retire <free|pay_as_you_go|pro> [--yes]

CLI: Platform and project

• org list | org create <name> <slug> | org members <org-id>
• org invite <org-id> <email> <role> | org member-role <org-id> <user-id> <role>
• org member-remove <org-id> <user-id> [--yes]
• project list <org-id> | project create <org-id> <name> <slug> [region]
• billing status <org-id> | billing checkout <org-id> <pay_as_you_go|pro>
• billing portal <org-id> | billing invoices <org-id> | billing usage <org-id>
• commerce status | commerce refresh | commerce configure-byo | commerce disconnect --yes
• commerce connect <country> <email> <return-url> <refresh-url>
• commerce products [--all] | commerce product-create <json> | commerce product-archive <id>
• commerce prices [--all] | 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 | api-key create <name> <scope,...> | api-key revoke <id> [--yes]

CLI: Database workflows

• sql <statement> | sql --file <path> | seed <path> | schema | policies
• migration create <name> | migration status | migration apply <path>
• migration rollback <id> [--yes]

CLI: Auth, storage, and email

• auth settings | auth set <json> | auth users | auth disable <id> [--yes] | auth enable <id>
• storage buckets | storage create-bucket <name> | storage cleanup
• email templates | email import-artifact <json> | email publish <kind> <version>

CLI: Operations

• logs [limit] | backup list | backup create | backup restore <id> [--yes]
• backup integrity | health | dev

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.

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.

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.

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.