FlowBase CLI

flowbase is the official command line client for the FlowBase OpenAPI. It manages apps, objects, fields, views, custom pages, workflows, approval flows, dashboards, business records, roles, and configuration versions across the three FlowBase environments.

1. Install and connect

python -m pip install ./packages/flowbase-cli

Connect to an environment by its site Base URL and a FlowBase API key:

export FLOWBASE_HOST=https://flowbase-test-a.deepflowagent.com
export FLOWBASE_API_KEY=fbk_xxx

The CLI appends /api/openapi/v1 automatically and sends Authorization: Bearer <key> plus an X-FlowBase-Channel: cli header. It never stores keys on disk and never prints the full key in errors.

2. Environments

FlowBase has three environments, selected only by the Host — never by a query, body, or extra header:

Most commands run on every Host; roles is production-only and changes commit/release is test-only.

3. Mental model

3.1 Metadata vs records

• Metadata (metadata scope): apps, objects, fields, views, pages, workflows, approvals, dashboards, roles, versions.
• Business records (records scope): rows inside an object.

Metadata changes are drafts against the current environment's configuration repository. They do not affect the running front-end until they are committed and released.

3.2 Draft → commit → release

metadata write commands  →  draft in the current environment
changes commit           →  snapshot draft into a new version (test env)
changes release          →  publish the current test version to production
changes direct-release   →  production hotfix: preflight + confirmation, then publish drafts

Most update commands accept an optional baseRevision to guard against concurrent edits; the server returns 409 if the draft moved since your last read.

3.3 Scope and confirmation

Each operation is in metadata:read, metadata:write, records:read, or records:write. Destructive commands (delete, restore, set-enabled, version operations) ask for confirmation in a terminal; in automation you must pass --yes.

4. Command groups

flowbase
├── docs            list | show | example | operations   Offline endpoint catalog
├── apps            list | get | create | update | set-enabled | delete
│                   add-objects | remove-object | set-group | reorder-objects
│                   add-dashboards | remove-dashboard | set-dashboard-group | reorder-members
├── groups          create | reorder | update | delete    App groups (under an app)
├── objects         list | get | create | update | delete | restore
│                   cli-edit-policy get | update
├── fields          create | update | delete | restore    Fields under an object
├── views           list | create | update | reorder | set-enabled | delete
├── workflows       list | get | create | update | reorder | set-enabled | delete | executions
├── approvals       list | get | create | update | reorder | set-enabled | delete
├── pages           list | options | get | create | update | set-default | delete | restore
├── dashboards      list | get | create | update | copy | delete
├── changes         commit | release | direct-release
├── versions        list | show | releases                Read-only history
├── environments    restart                              Destructive test-env reset
├── records         list | get | create | update | delete | upload-attachment | download-attachment
└── roles           list | options | get | create | update | delete   (production only)

Global flags: --host, --api-key, --pretty/--no-pretty, --raw.

5. Discovering request bodies

JSON writes accept --json or --json-file. The CLI is self-describing:

flowbase docs list                       # endpoints + hasRequestBody/requiresConfirmation flags
flowbase docs show dashboards.update     # metadata + representative request body
flowbase docs example dashboards.update --output dashboard.json
flowbase dashboards update dsh_xxx --json-file dashboard.json

flowbase docs example <key> prints a representative body template for that endpoint so you can edit it instead of writing from scratch.

Closed-domain catalogs

Complex bodies reference closed sets that are not guessable from examples. Query them offline:

flowbase docs catalogs                    # list available catalogs
flowbase docs catalogs field-types        # field type names + allowed constraints
flowbase docs catalogs workflow-nodes     # node types with in/out edge rules
flowbase docs catalogs permissions        # function permission points + data scopes
flowbase docs catalogs dashboard-filters  # filter types + date-range presets
flowbase docs catalogs page-components    # page region component kinds (field / relatedList / approval)
flowbase docs catalogs id-prefixes        # resource ID prefix meanings
flowbase docs catalogs icons              # icon guidance + examples

The read → modify → write loop

Most update commands replace a full snapshot and accept an optional baseRevision for optimistic locking. The safe pattern is:

flowbase dashboards get dsh_xxx > current.json      # authoritative snapshot
# edit current.json: change fields, keep filters/components, use draftRevision as baseRevision
flowbase dashboards update dsh_xxx --json-file current.json

Do not compose update bodies from scratch when an existing resource exists — get returns the server-valid shape, including baseRevision.

6. Recipes

6.1 Create an object with a field and a record

flowbase objects create --label Customer --key customer --description "Customer records"
flowbase fields create obj_xxx --json '{"label":"Name","key":"name","description":"Customer name","type":"text.singleLine","permission":"required"}'
flowbase records create obj_xxx --json '{"values":{"name":"Acme Corp"}}'
flowbase objects cli-edit-policy get obj_xxx
flowbase objects cli-edit-policy update obj_xxx --json '{"baseRevision":4,"policies":{"fld_xxx":"user_approval"}}' --yes

Record values keys are field keys (name), not internal IDs (fld_...). IDs are obj_/fld_/dsh_/wfl_/pag_/reg_/cmp_-prefixed; see docs catalogs id-prefixes.

6.2 Edit and publish configuration on a test environment

export FLOWBASE_HOST=https://flowbase-test-a.deepflowagent.com

flowbase dashboards create --label "Sales board" --key sales_board
flowbase docs example dashboards.update --output dashboard.json   # fill filters/components
flowbase dashboards update dsh_xxx --json-file dashboard.json
flowbase apps add-dashboards app_xxx dsh_xxx
flowbase apps reorder-members app_xxx --json '{"items":[{"type":"object","id":"obj_xxx"},{"type":"dashboard","id":"dsh_xxx"}]}'
flowbase changes commit --message "Add sales dashboard" --yes
flowbase changes release --message "Ship sales dashboard" --yes

Dashboard component code runs server-side in a sandbox and returns ECharts config / metric / table / markdown. Components and filters are validated on save; runtime results are only visible in the web UI, not through this CLI.

6.3 Production hotfix

export FLOWBASE_HOST=https://flowbase.deepflowagent.com
flowbase changes direct-release --message "Fix customer field" --yes

direct-release always runs a server-side preflight, prints the current version, diff summary, checks and risk, and binds a one-time confirmation token. --yes accepts that reviewed result; it never skips validation.

6.4 Workflows, approvals, and pages

A workflow graph must satisfy structural rules: exactly one trigger node, at least one end node, a DAG, and valid per-type edges. See docs catalogs workflow-nodes before composing nodes/edges.

Approval flow graphs are separate metadata: exactly one trigger, at least one approval node, both approvedEnd and rejectedEnd, and dual outcome edges from each approval node. Employee task decisions are not available via API key / CLI. See docs catalogs approval-nodes.

flowbase docs catalogs workflow-nodes
flowbase workflows create obj_xxx --json '{"label":"Set owner","enabled":true,"trigger":{"event":"create","match":"all","conditions":[]},"nodes":[],"edges":[]}'
flowbase workflows update obj_xxx wfl_xxx --json-file workflow.json
flowbase workflows executions obj_xxx wfl_xxx --result failure

flowbase docs catalogs approval-nodes
flowbase docs example approvals.create --output approval.json
flowbase approvals create obj_xxx --json-file approval.json
flowbase approvals set-enabled obj_xxx apr_xxx --base-revision 4 --enabled --yes

flowbase docs catalogs page-components                  # field + relatedList + approval keys
flowbase docs example pages.create --output page.json   # create-page layout template
flowbase pages create --json-file page.json
flowbase pages set-default pag_xxx --base-revision 4 --yes

# Detail pages may embed relatedList and at most one approval component.
flowbase pages get pag_xxx > page.json                  # prefer get → edit → update
# or: flowbase docs example pages.update --output page.json
flowbase pages update pag_xxx --json-file page.json

6.5 Records and attachments

flowbase records list obj_xxx --page 1
flowbase records get obj_xxx rec_xxx
flowbase records upload-attachment obj_xxx fld_xxx ./contract.pdf
flowbase records update obj_xxx rec_xxx --json '{"values":{"fld_contract":["att_xxx"]}}'
flowbase records download-attachment obj_xxx rec_xxx att_xxx --output ./contract.pdf

6.6 Roles (production only)

export FLOWBASE_HOST=https://flowbase.deepflowagent.com
flowbase docs catalogs permissions      # function points + data scopes
flowbase roles options                  # apps and objects available for grants
flowbase roles create --json-file role.json
flowbase roles update rol_xxx --json-file role.json

7. Output and errors

• Success: JSON on stdout, exit code 0. Use --no-pretty for compact JSON or --raw for the raw body.
• Failures (missing key, invalid JSON, HTTP 4xx/5xx, network errors, cancelled confirmation) go to stderr with a clear message and exit code 1.
• flowbase --help lists every command; flowbase <group> --help and flowbase <group> <action> --help show flags and, for JSON commands, an inline body example.

Error matrix