flowbase-cli 0.1.9__tar.gz → 0.1.11__tar.gz

{flowbase_cli-0.1.9 → flowbase_cli-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowbase-cli
-Version: 0.1.9
+Version: 0.1.11
 Summary: Command line client for the FlowBase OpenAPI
 Author: DeepFlowAI
 License: Apache-2.0
@@ -11,6 +11,8 @@ Description-Content-Type: text/markdown
 
 `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
@@ -72,6 +74,8 @@ Each operation is in `metadata:read`, `metadata:write`, `records:read`, or `reco
 ```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
@@ -82,8 +86,8 @@ flowbase
 ├── 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
+├── 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
@@ -91,7 +95,7 @@ flowbase
 └── roles           list | options | get | create | update | delete   (production only)
 ```
 
-Global flags: `--host`, `--api-key`, `--pretty`/`--no-pretty`, `--raw`.
+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
 
@@ -112,18 +116,24 @@ Complex bodies reference closed sets that are not guessable from examples. Query
 
 ```bash
 flowbase docs catalogs                    # list available catalogs
-flowbase docs catalogs field-types        # field type names + allowed constraints
+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 region component kinds (field / relatedList / approval)
+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. The safe pattern is:
+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
@@ -131,20 +141,24 @@ flowbase dashboards get dsh_xxx > current.json      # authoritative snapshot
 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`.
+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 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 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
@@ -161,7 +175,7 @@ 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.
+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
 
@@ -172,10 +186,14 @@ 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
@@ -189,24 +207,39 @@ 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 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 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
+# 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":{"fld_contract":["att_xxx"]}}'
+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
 ```
 
@@ -236,3 +269,13 @@ flowbase roles update rol_xxx --json-file role.json
 | 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.9 → flowbase_cli-0.1.11}/README.md

@@ -2,6 +2,8 @@
 
 `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
@@ -63,6 +65,8 @@ Each operation is in `metadata:read`, `metadata:write`, `records:read`, or `reco
 ```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
@@ -73,8 +77,8 @@ flowbase
 ├── 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
+├── 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
@@ -82,7 +86,7 @@ flowbase
 └── roles           list | options | get | create | update | delete   (production only)
 ```
 
-Global flags: `--host`, `--api-key`, `--pretty`/`--no-pretty`, `--raw`.
+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
 
@@ -103,18 +107,24 @@ Complex bodies reference closed sets that are not guessable from examples. Query
 
 ```bash
 flowbase docs catalogs                    # list available catalogs
-flowbase docs catalogs field-types        # field type names + allowed constraints
+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 region component kinds (field / relatedList / approval)
+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. The safe pattern is:
+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
@@ -122,20 +132,24 @@ flowbase dashboards get dsh_xxx > current.json      # authoritative snapshot
 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`.
+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 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 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
@@ -152,7 +166,7 @@ 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.
+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
 
@@ -163,10 +177,14 @@ 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
@@ -180,24 +198,39 @@ 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 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 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
+# 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":{"fld_contract":["att_xxx"]}}'
+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
 ```
 
@@ -227,3 +260,13 @@ flowbase roles update rol_xxx --json-file role.json
 | 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.9 → flowbase_cli-0.1.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flowbase-cli"
-version = "0.1.9"
+version = "0.1.11"
 description = "Command line client for the FlowBase OpenAPI"
 readme = "README.md"
 requires-python = ">=3.11"

{flowbase_cli-0.1.9 → flowbase_cli-0.1.11}/src/flowbase_cli/__init__.py

@@ -1,3 +1,3 @@
 """FlowBase OpenAPI CLI."""
 
-__version__ = "0.1.9"
+__version__ = "0.1.11"