flowbase-cli 0.1.6__tar.gz → 0.1.7__tar.gz

flowbase_cli-0.1.7/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: flowbase-cli
+Version: 0.1.7
+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, dashboards, business records, roles, and configuration versions across the three FlowBase environments.
+
+## 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, 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
+├── 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
+├── 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
+├── 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:
+
+```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 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 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:
+
+```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 — `get` returns the server-valid shape, including `baseRevision`.
+
+## 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 records create obj_xxx --json '{"values":{"name":"Acme Corp"}}'
+```
+
+Record `values` keys are **field keys** (`name`), not internal IDs (`fld_...`). IDs are `obj_`/`fld_`/`dsh_`/`wfl_`/`pag_`-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; runtime results are only visible in the web UI, not through this CLI.
+
+### 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.
+
+### 6.4 Workflows 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`.
+
+```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 example pages.create --output page.json   # authoritative layout template
+flowbase pages create --json-file page.json
+flowbase pages set-default pag_xxx --base-revision 4 --yes
+```
+
+### 6.5 Records and attachments
+
+```bash
+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)
+
+```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 |

flowbase_cli-0.1.7/README.md

@@ -0,0 +1,211 @@
+# FlowBase CLI
+
+`flowbase` is the official command line client for the FlowBase OpenAPI. It manages apps, objects, fields, views, custom pages, workflows, dashboards, business records, roles, and configuration versions across the three FlowBase environments.
+
+## 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, 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
+├── 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
+├── 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
+├── 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:
+
+```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 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 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:
+
+```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 — `get` returns the server-valid shape, including `baseRevision`.
+
+## 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 records create obj_xxx --json '{"values":{"name":"Acme Corp"}}'
+```
+
+Record `values` keys are **field keys** (`name`), not internal IDs (`fld_...`). IDs are `obj_`/`fld_`/`dsh_`/`wfl_`/`pag_`-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; runtime results are only visible in the web UI, not through this CLI.
+
+### 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.
+
+### 6.4 Workflows 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`.
+
+```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 example pages.create --output page.json   # authoritative layout template
+flowbase pages create --json-file page.json
+flowbase pages set-default pag_xxx --base-revision 4 --yes
+```
+
+### 6.5 Records and attachments
+
+```bash
+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)
+
+```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 |

{flowbase_cli-0.1.6 → flowbase_cli-0.1.7}/pyproject.toml

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

{flowbase_cli-0.1.6 → flowbase_cli-0.1.7}/src/flowbase_cli/__init__.py

@@ -1,3 +1,3 @@
 """FlowBase OpenAPI CLI."""
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"