Metadata-Version: 2.4
Name: flowbase-cli
Version: 0.1.8
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 page-components    # page region component kinds (field / relatedList)
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_`/`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 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 catalogs page-components                  # field + relatedList 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 components (reverse lookup lists).
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 |
