Metadata-Version: 2.4
Name: flowbase-cli
Version: 0.1.9
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.

## 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
├── 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:

```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 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:

```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"}}'
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

```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, 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`.

```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                  # 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

```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 |
