@formbuilder-cloud/cli

fb is the command line for the formBuilder Cloud API, a form builder API and headless forms backend. With it you create forms from formBuilder definitions, push drafts, publish, list and export submissions, and manage API keys. Scripts, CI jobs and AI coding agents can run every command with nothing but FORMBUILDER_API_KEY in the environment: --json works on every command, the exit codes are documented, and nothing prompts without a TTY. It is built on the typed SDK, @formbuilder-cloud/sdk.

Status: 0.1.0, not published yet. The package name is @formbuilder-cloud/cli and the command is fb. Node 20+. No telemetry and no update checks: the only requests are the ones your command makes, to the API base URL.

Quickstart

npm i -g @formbuilder-cloud/cli        # or: npx @formbuilder-cloud/cli <command>
export FORMBUILDER_API_KEY=fb_mgmt_…   # a write management key (dashboard → API keys)

fb whoami
fb projects list
form=$(fb forms create --project <project-id> --name Contact)
fb drafts push "$form" contact.json    # the formBuilder field array
fb forms publish "$form"
fb keys mint --kind collection --form "$form"   # prints the collection key once, for the embed
fb submissions list "$form"
fb submissions export "$form" --format csv --output submissions.csv

No account yet? fb sandbox create needs no key. It opens a 7-day sandbox and prints a management key, a collection key and a published starter form as KEY=value lines (when the API enables sandboxes):

fb sandbox create > sandbox.env && chmod 600 sandbox.env
set -a; . ./sandbox.env; set +a        # FORMBUILDER_API_KEY, FORMBUILDER_COLLECTION_KEY, FORMBUILDER_FORM_ID, …
fb whoami
fb submissions list "$FORMBUILDER_FORM_ID"

contact.json holds the field array that formBuilder's formData gives you, for example:

[{ "type": "text", "subtype": "email", "name": "email", "label": "Email", "required": true }]

Authentication

The key is looked up in this order; the first one found wins:

1. --api-key <key>. It works, but the key is then visible in your shell history and in the process list (ps), so fb prints a warning on stderr. Use one of the next two instead.

   • --api-key - reads the key from the first line of stdin (fb whoami --api-key - < key.txt). It is refused when stdin is a terminal: fb never prompts for a key.
   • --api-key-file <path> reads the first line of a file. fb warns when the file is readable by other users (chmod 600 it).

   Only one of these flags may be given.

2. FORMBUILDER_API_KEY. This is the normal way in CI and for agents.

An empty value counts as unset. With no key at all, the command exits with code 3 before sending anything.

Base URL: --base-url <url>, else FORMBUILDER_BASE_URL, else https://api.formbuilder.online. Like the SDK, fb accepts only https: URLs, plus http: for loopback hosts (localhost, *.localhost, 127.0.0.0/8, [::1], i.e. the dev stack). A URL with credentials, a query or a fragment is refused. The key never travels in clear text over a network.

Which key:

• A management key (fb_mgmt_…, scope read or write) works for every command. A read key can list and export but cannot change anything (403, exit 3).
• A collection key (fb_col_…) can only submit to its one form, so management commands refuse it (exit 3).
• Management keys are minted by workspace owners only (S-05 §2). A key can never mint a management key, so fb keys mint --kind mgmt gets a 403 from the API (exit 3). Mint management keys in the dashboard. A write management key can mint and revoke collection keys.
• A management key acts at most as an editor, so it also gets a 403 for the other owner-only options: submissions list --deleted and submissions export --include-client-meta.

The key is never printed, not even partly. fb whoami and error messages show only its kind, e.g. fb_mgmt_[redacted]. Everything fb writes to stderr is filtered, so any fb_mgmt_…/fb_col_… key or fb_sbx_… sandbox token that shows up there is replaced the same way. The only keys fb ever prints are the ones fb keys mint or fb sandbox create creates, printed once, on stdout. fb writes no log or config file.

There is no fb login yet: humans use an API key too. Kevin approved API keys only at beta, with fb login after beta (decision-register item 28, 2026-10-21).

Commands

Every command accepts --help/-h (e.g. fb forms create --help, or fb help forms create), --json, the auth flags above and --no-color. fb --version prints the version.

| Command | What it does | API | |---|---|---| | fb whoami (alias fb me) | The key's kind, scope and workspace (a user token: the user and their workspaces) | GET /v1/me | | fb projects list | The workspace's projects | GET /v1/workspaces/{ws}/projects | | fb projects create --name <name> | Create a project | POST /v1/workspaces/{ws}/projects | | fb forms list [--project <id>] [--status active\|archived\|all] [--query <text>] | Forms of the workspace or of one project | GET /v1/workspaces/{ws}/forms | | fb forms get <form> | One form | GET /v1/forms/{f} | | fb forms create --project <id> --name <name> [--definition <file\|->] | Create a form; prints its id. --definition sets the first draft | POST /v1/projects/{p}/forms | | fb forms publish <form> | Publish the draft as a new version. If the draft hasn't changed, the active version stays and the exit code is still 0 | POST /v1/forms/{f}:publish | | fb drafts get <form> | Print the draft's field array (--json: with etag and updated_at) | GET /v1/forms/{f}/draft | | fb drafts push <form> <file.json\|-> [--if-match <etag>] [--check] | Save the file as the draft. --check exits 5 when the draft would not publish | PUT /v1/forms/{f}/draft | | fb submissions list <form> [filters] | Submissions, newest first | GET /v1/forms/{f}/submissions | | fb submissions export <form> --format csv\|json\|ndjson [--output <file>] [filters] | The export, streamed | GET /v1/forms/{f}/submissions/export | | fb keys list | The workspace's API keys, revoked ones included (key_prefix, never a key) | GET /v1/workspaces/{ws}/credentials | | fb keys get <key-id> | One key of the workspace, revoked or not (key_prefix, never a key) | GET /v1/workspaces/{ws}/credentials/{id} | | fb keys mint --kind collection --form <id> [--label <text>]fb keys mint --kind mgmt --scope read\|write [--label <text>] | Mint a key; the plaintext is printed once | POST /v1/workspaces/{ws}/credentials | | fb keys revoke <key-id> [--yes] | Revoke a key | DELETE /v1/credentials/{id} | | fb sandbox create | No key needed: open an anonymous 7-day sandbox and print its expiring key pair, starter form, session token and claim link once (KEY=value lines; --json: the API answer). 3 forms, 100 submissions, 5 a day per address, delivery simulated. Exit 4 when the API does not enable sandboxes | POST /v1/sandbox/sessions {"keys": true} |

Workspace: a management key belongs to one workspace, and fb reads it from GET /v1/me. --workspace <id> skips that lookup.

Lists show one page: --limit <1..100> sets the page size, and --cursor <cursor> continues from the next_cursor that the previous page printed. --all follows every page, fetching one page at a time.

Submission filters (list and export): --from and --to take ISO 8601 date-times with a time zone (--to is exclusive). Also --form-version <n>, --delivery none|pending|retrying|delivered|failed|cancelled and --spam include|exclude|only. List only: --deleted shows deleted submissions (owners). Export only: --headers name|label, --no-bom (CSV) and --include-client-meta (owners).

Drafts: the file may be the bare field array, or an object with a definition array. So fb drafts get <form> --json > draft.json round-trips, and so does a form export's draft. - reads stdin. fb checks only that the input is JSON and an array of objects that each have a type. The API validates the rest, and its errors are printed. The answer's publish_check says whether the draft would publish, and fb warns when it would not.

Export is streamed from the API to stdout or to the file, chunk by chunk, so a large export is never held in memory. With --output, the data goes into a temporary file next to the target (mode 0600, since exports hold personal data). The temporary file is renamed over the target only once the export is complete. If the connection breaks, fb deletes the temporary file, leaves the target as it was, and exits 6. On stdout, a broken export is incomplete: retry the whole export. When stdout is a terminal, fb drops control characters (escape sequences a submitted value could carry) from what it shows; piped or redirected, the bytes are exact.

Revoking cannot be undone. On a terminal, fb keys revoke asks first. Without a TTY on stdin, stdout and stderr, or with --json, it never asks and needs --yes (otherwise it exits 2 and sends nothing).

Output

• Human (default): tables and short sentences on stdout; notes, warnings and errors on stderr. Colour appears only on a terminal stderr, and never with NO_COLOR, --no-color, --json or TERM=dumb. Values that come from submissions are printed without control characters, so a submission can't drive your terminal. Some commands print exactly one thing on stdout, so you can capture it with $(…): forms create prints the new form id, keys mint the new key. sandbox create prints KEY=value lines meant for an env file.
• --json: stdout is machine-readable.
  • Most commands print one JSON document: the API's answer as is. A list prints the page { "items": [...], "next_cursor": ... }, keys revoke prints { "id": ..., "revoked": true }, and --version prints { "name", "version", "sdk_version" }.
  • With --all, stdout is NDJSON: one item per line, across every page.
  • submissions export writes the export itself, also with --json. With --output and --json, it prints { "output", "format", "bytes" }.
  • JSON is compact when piped and indented on a terminal.
  • stderr carries one JSON object per line: {"warning": "..."} and {"note": "..."}. When a command fails, the last line is an RFC 7807 problem document.
• Errors: an API error is printed as the API's own problem document (type, title, status, detail, errors, hint, …, with any key redacted). An HTTP answer that is not a problem document becomes { "type": "about:blank", "title": "HTTP 502", "status": 502 }. Errors that fb detects itself use these types:

| type | When | |---|---| | urn:formbuilder-cloud:cli:usage | Bad command, flag, argument or input file (exit 2) | | urn:formbuilder-cloud:cli:auth | No key, an empty key, or a malformed key (exit 3) | | urn:formbuilder-cloud:cli:network / …:timeout | The API could not be reached, or did not answer in time (exit 6) | | urn:formbuilder-cloud:cli:io | A local file could not be written, or an export stream broke (exit 1 or 6) | | urn:formbuilder-cloud:cli:publish-check | drafts push --check and the draft would not publish (exit 5) | | urn:formbuilder-cloud:cli:aborted | You answered no to a confirmation (exit 1) | | urn:formbuilder-cloud:cli:interrupted | Ctrl-C (exit 130) | | urn:formbuilder-cloud:cli:internal | An unexpected error inside fb (exit 1) |

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Any other error: a 500 internal, a local I/O error, a declined confirmation | | 2 | Usage: an unknown command or flag, a missing or invalid argument, an unreadable input file, --yes missing without a TTY. Nothing was sent | | 3 | Authentication or permission: no key or a malformed key, 401 unauthenticated, 403 forbidden / origin-not-allowed | | 4 | Not found or gone: 404, and the 410s (archived form, retired or unknown version, suspended workspace) except collection-paused | | 5 | Rejected as sent: 400, 409, 412, 413, 415, 422, and 429 quota-exceeded. Repeating the same request won't help | | 6 | Try again later: 429 rate-limited, 410 collection-paused, 502/503/504, a network failure, a timeout, a broken export stream | | 130 | Interrupted (Ctrl-C) |

Before an error reaches you, fb retries safe requests (GET, and the operations the API marks x-fbc-idempotent, such as publish, activate and revoking a key; a submit only with its Idempotency-Key) after network failures and retryable answers. It makes at most 3 attempts and honours Retry-After up to 60 s. These are the SDK's defaults.

In CI

- name: Publish the contact form
  env:
    FORMBUILDER_API_KEY: ${{ secrets.FORMBUILDER_API_KEY }}   # a write management key
  run: |
    npx @formbuilder-cloud/cli drafts push "$FORM_ID" forms/contact.json --check
    npx @formbuilder-cloud/cli forms publish "$FORM_ID" --json | jq .version

Nothing prompts, colour is off (no TTY), and the exit code tells the job what happened. Pass --yes to keys revoke.

Licence

Proprietary: UNLICENSED, see LICENSE. You may use it only with the formBuilder Cloud service, under that service's terms.