flowbase-cli 0.1.12__py3-none-any.whl

flowbase_cli-0.1.12.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: flowbase-cli
+Version: 0.1.12
+Summary: Command line client for the FlowBase OpenAPI
+Author: DeepFlowAI
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 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.
+
+FlowBase is a low-code platform. Start with `flowbase guide` (offline): discover apps and objects, read fields, then configure and verify. Use `flowbase guide --format json` for structured guidance.
+
+## 1. Install and connect
+
+```bash
+python -m pip install ./packages/flowbase-cli
+```
+
+Connect to an environment by its site Base URL and a FlowBase API key:
+
+```bash
+export FLOWBASE_HOST=https://flowbase-test-a.deepflowagent.com
+export FLOWBASE_API_KEY=fbk_xxx
+```
+
+| Setting | Source |
+| --- | --- |
+| Host | `--host` > `FLOWBASE_HOST` > `http://flowbase.localhost:5001` |
+| API key | `--api-key` > `FLOWBASE_API_KEY` |
+
+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:
+
+| Environment | Host |
+| --- | --- |
+| Production | `https://flowbase.deepflowagent.com` |
+| Test A | `https://flowbase-test-a.deepflowagent.com` |
+| Test B | `https://flowbase-test-b.deepflowagent.com` |
+
+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
+
+```text
+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
+
+```text
+flowbase
+├── docs            list | show | example | operations   Offline endpoint catalog
+├── guide           Offline product and task guide (--format markdown|json)
+├── organization    employees | departments
+├── 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 | clear-default | delete | restore | evaluate
+├── dashboards      list | get | create | update | copy | delete | run
+├── 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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+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
+```
+
+`records create` returns `{recordId}`; use it with `records get`.
+
+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
+
+```bash
+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; use `flowbase dashboards get <id>` to discover component IDs, then `flowbase dashboards run <dashboard_id> <component_id>` to inspect `ok/output/error/logs` in a read-only draft preview (requires metadata:read and records:read). Visual chart rendering still requires the web UI.
+
+### 6.3 Production hotfix
+
+```bash
+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`.
+
+```bash
+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.
+
+```bash
+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)
+
+```bash
+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
+
+| Scenario | HTTP / CLI behavior |
+| --- | --- |
+| Missing or invalid API key | 401; stderr tells you to set `FLOWBASE_API_KEY` or `--api-key` |
+| Environment not enabled | 403; request is rejected before business logic |
+| Missing draft revision / concurrent edit | 409; re-read with `get` and retry with the new `baseRevision` |
+| Invalid request field or business rule | 400 / 422; `detail` explains the reason |
+| Resource not found | 404 |
+| Destructive command without `--yes` in automation | CLI refuses before any network call |
+
+## 8. Verification and cleanup
+
+- `flowbase organization employees --query Ada --page 1`: discover real approval references; follow the returned `pages`. `organization departments` returns the full department tree.
+- `flowbase records list obj_xxx --view-id viw_xxx`: query a specific active view. Invalid IDs return an error instead of silently selecting another view.
+- `flowbase pages evaluate pag_xxx --json '{"values":{"done":true}}'`: evaluate draft rules on editor-style values. Returns rule overrides keyed by field/component IDs; does not render a page, validate record values, execute buttons, or write records.
+- `flowbase pages clear-default pag_xxx --base-revision 4 --yes`: remove only this page's default assignment, including on a deleted object, then use `pages delete` with the newly returned revision.
+- `docs catalogs page-buttons`, `workflow-branches`, `approval-rules`, and `dashboard-runtime` describe complex configuration and runtime limits.
+
+Transport requests time out after 60 seconds. A lost write response has an unknown outcome: read the resource and current revision before retrying. The CLI never automatically retries writes.

flowbase_cli-0.1.12.dist-info/RECORD

@@ -0,0 +1,9 @@
+flowbase_cli/__init__.py,sha256=e4KIz7k_3kja21MuC3NjQjskgBHOQgMNENP5NBJnJds,52
+flowbase_cli/endpoints.py,sha256=W4bKCPuzrbZuBzivesCy87n-i5X4PafelaPr6KtHGBQ,79887
+flowbase_cli/guide.py,sha256=zv6RgcGkmpAexR7NwBDwZFqubTqStSjNN57j2tcLR8Y,3949
+flowbase_cli/main.py,sha256=Dwq6ngVshfMjufyggAmZVdnu6uT2t6rnbOu9K0pTG1k,63362
+flowbase_cli-0.1.12.dist-info/METADATA,sha256=NGgaUomf6FmJ0xrdmqh7yCpF0pWFkI6FN13S8PX9FiY,16412
+flowbase_cli-0.1.12.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flowbase_cli-0.1.12.dist-info/entry_points.txt,sha256=kb3ZwOcvIIJ-2W3yyWgn7luZVbPsj57YusOyoIOv2YA,58
+flowbase_cli-0.1.12.dist-info/top_level.txt,sha256=As7iuQHHfVT5d2WJ0cCN22Mmp0gTiOcoPpM0OC3XJxQ,13
+flowbase_cli-0.1.12.dist-info/RECORD,,

flowbase_cli-0.1.12.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flowbase_cli-0.1.12.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flowbase = flowbase_cli.main:entrypoint

flowbase_cli-0.1.12.dist-info/top_level.txt

@@ -0,0 +1 @@
+flowbase_cli