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. They may appear before or after the subcommand (flowbase apps list --no-pretty is valid).

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 authoring          # required fields, draftRevision sources, common mistakes
flowbase docs catalogs field-types        # types, constraints, filter operators, record values, create examples
flowbase docs catalogs view-filters       # view filter operators and value shapes (not page-rules)
flowbase docs catalogs record-values      # how to write records.values by field type
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 component shapes, placement, fields, and enums
flowbase docs catalogs page-rules         # Page condition operators and action shapes
flowbase docs catalogs id-prefixes        # resource ID prefix meanings
flowbase docs catalogs icons              # icon guidance + examples

Read authoring before composing any write. It lists the mistakes that most often make generated commands fail: missing description/type, select options without id+lifecycle, defaultValue: null (omit the key instead), boolean view filters using eq, records.list being a column projection, pages.list.pages being a page count, and objects.get not returning draftRevision.

The read → modify → write loop

Most update commands replace a full snapshot and accept an optional baseRevision for optimistic locking. Check the relevant offline catalog for its exact update envelope and read-only response fields. 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. Start from get, then convert its read projection to the update envelope documented by the relevant catalog.

6. Recipes

6.1 Create an object with a field and a record

flowbase docs catalogs authoring
flowbase docs catalogs field-types
flowbase objects create --json '{"label":"Customer","key":"customer","description":"Customer records","icon":"IconUsers"}'
flowbase fields create obj_xxx --json '{"label":"Name","key":"name","description":"Customer name","type":"text.singleLine","typeVersion":"v1","permission":"required","constraints":{"maxLength":120}}'
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.

On production, records.* sees released metadata only. Creating records on a brand-new object before direct-release returns 404 内容不存在或已被删除. Finish metadata, release, then seed.

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.

Workflow conditions use fieldId for current-object fields and add relationFieldId for a one-hop related field. Field-value references use valueRef plus optional valueRefRelationFieldId. An updateRelated node selects the target record with its required relationFieldId; its assignment fieldId values belong to that related object. Use workflows list to retrieve the current object fields and the available relations with target fields.

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                  # all component shapes and placement rules
flowbase docs catalogs page-rules                       # conditions, operators, and actions
flowbase pages options                                  # objects, fields, and lookup constraints
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 support detailSummary, stageBar, tabs, relatedSummary,
# attachmentCard, noticeBlock, relatedList, and approval components.
# A placed field uses sourcePath=[] for the Page object, or 1-2
# {relationFieldId,targetObjectId} hops for a related object field.
# Component visibility uses a page-rules setComponentVisibility action
# targeting the stable cmp_ ID returned by pages get.
# Save and read back a newly added component before adding a rule for it.
flowbase pages get pag_xxx > page-read.json
# Build page.json as {baseRevision: page-read.draftRevision, page: page-read.page},
# then remove the read-only Page keys listed by page-components.
# Or start from the complete offline example:
flowbase docs example pages.update --output page.json
flowbase pages update pag_xxx --json-file page.json

6.5 Records and attachments

records.list is a column projection of the current view (often only the title field). Use records.get for the full values object. values keys are field keys; select/lookup values are option/record IDs.

flowbase records list obj_xxx --page 1
flowbase records get obj_xxx rec_xxx
flowbase docs catalogs record-values
flowbase records create obj_xxx --json '{"values":{"name":"Ada","status":"opt_xxx","class":"rec_xxx"}}'
flowbase records upload-attachment obj_xxx fld_xxx ./contract.pdf
flowbase records update obj_xxx rec_xxx --json '{"values":{"attachments":["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