Metadata-Version: 2.4
Name: flowbase-cli
Version: 0.1.19
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 | navigation
│                   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
│                   record-view-options | record-view-preview | records
├── 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 forms              # custom form fields, rules, appearance, and settings
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
# Keep only label/description/icon/filters/components; use draftRevision as baseRevision.
# Edit the desired fields while preserving all other components and filters.
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`.

To add existing objects to an application, pass their IDs with `--object-ids`:

```bash
flowbase apps add-objects app_xxx --object-ids obj_a,obj_b
```

Use a comma-separated list for multiple objects. Object IDs are not positional arguments. Run `flowbase docs show apps.objects.add` for the endpoint details.

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.

App sections and record-view components:

```bash
flowbase apps get app_xxx
flowbase docs catalogs app-sections
flowbase apps navigation app_xxx --json '{"type":"appSection.create","name":"Sales"}' --yes
flowbase groups create app_xxx --name Orders --section-id sec_xxx
flowbase apps add-objects app_xxx --object-ids obj_xxx --section-id sec_xxx
# add-dashboards and add-iframes also accept --section-id.
flowbase apps navigation app_xxx --json '{"type":"appMember.move","id":"obj_xxx","sectionId":"sec_xxx","groupId":"grp_xxx","expectedSectionId":"sec_xxx","expectedGroupId":null}' --yes

flowbase docs catalogs dashboard-record-views
flowbase dashboards record-view-options
flowbase docs example dashboards.record-view-preview --output preview.json
# Replace placeholder IDs and configure component/filters before previewing.
flowbase dashboards record-view-preview dsh_xxx --json-file preview.json
flowbase dashboards records dsh_xxx dcm_xxx --page 1 --query Orders --json '{"filterValues":{}}'
```

`apps get` preserves section definitions and group/member `sectionId`. Navigation supports section creation, rename, empty-section deletion, full section ordering, group moves and member moves. Moves require explicit source and target positions; use JSON `null` for unassigned/ungrouped. See `app-sections` for all six request bodies. Navigation requires confirmation (`--yes` for automation), and writes only a draft.

Record-view previews and queries require both `metadata:read` and `records:read`, use the current Host's records and draft configuration, and return `mode: draft-preview` plus `draftRevision`. They use API-key visibility rather than an employee's workspace identity; hidden fields stay excluded and hidden filter fields are rejected. Page size is configured on the component (10/20/50). Search is ignored when `showSearch` is false. `dashboards run` is for code components.

For `dashboards update`, construct the body from the latest `get`: preserve `label`, `description`, `icon`, `filters`, and **all** `components`; set `baseRevision` to the returned `draftRevision`. Omit response-only fields. Keep existing component IDs and `recordView` unchanged when editing other properties; omit IDs on new components. Omitting `components` or `filters` clears them.

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

### Recent feature authoring

- `flowbase docs catalogs field-types`: includes template autonumber configuration and date/time/datetime v2 creation examples. Numbering rules and temporal precision are immutable after creation; legacy numbering and temporal v1 remain supported.
- `flowbase docs catalogs planning`: tree/Gantt view snapshots, candidate queries and optimistic plan updates. Read a full view with `views list` before updating; preserve `displayMode`, `parentFieldId` and `gantt`.
- `flowbase docs catalogs record-bundles`: initialize, atomically submit and recover a parent/detail submission. Reuse a submission ID only with the identical request body.
- `flowbase docs catalogs formula-authoring`: formula/rollup sources, validation, saved-record trials and runtime draft preview. Supports reuse of calculated results through single relations and multi-level rollups (up to 10 dependency levels). Validation returns `dependencyGraph`, or `valid=false` with `code`/`errorPath` for invalid dependencies. Pass `fieldId` when validating an existing field. Derived values are read-only.
- `flowbase docs catalogs workflow-python`: record creation examples and failed-task retry. `workflows python-runtime OBJECT new` discovers current object bindings; `workflows executions` includes Python attempts, logs and `canRetry`.

Use `records list OBJECT --view-id VIEW --view-layout` for tree/Gantt projections; the default remains a flat list. `records update` accepts `updatedAt` and `planViewId` in its JSON body for version-checked plan edits. Formula validation and custom-sample trials require metadata read; saved-record trials also require record read; workflow retry requires both metadata write and record write and explicit CLI confirmation (`--yes` in automation).

### Single-select formulas (4.21)

Use `flowbase formulas sources OBJECT` to discover local and one-hop single-select paths and their `options` (`id`, `label`, `lifecycle`). Use the returned stable option ID in `is_option(path, "OPTION_ID")`; `option_label(path)` reads the current label. Inactive options can model historical values. Raw single-select values cannot be compared with strings or returned directly.

Save a request such as this as `formula.json`, replacing the path and option ID with the source discovery response:

```json
{
  "constraints": {"expression": "is_option(direction, \"OPTION_ID\")", "resultType": "boolean"},
  "samples": {"direction": "OPTION_ID"},
  "trial": true
}
```

Run `flowbase formulas validate OBJECT --json-file formula.json`. For label output, use `option_label(direction)` with `resultType: "text.singleLine"`. Samples are stable option IDs or `null`; use `recordId` instead to test an accessible saved record. Inspect `valid`, `optionReferences` and `trial.status`: HTTP success alone does not mean the formula or trial succeeded. Save valid configuration through the existing `fields create` / `fields update` commands (metadata write permission).

These commands require a backend with 4.21 support. Existing CLI installations that already provide `formulas sources` and `formulas validate` can send the new expressions; updated offline help requires the updated CLI package. Employee CLI consumers continue reading calculated values and states through record commands.

### Conditional query rollups (4.23)

Read `flowbase docs catalogs conditional-rollup`, then discover stable IDs with `flowbase formulas collections OBJECT`. A query source uses `mode: "query"`, `objectId`, and 1–50 `conditions` of `{fieldId, operator, currentFieldId}`. All matching conditions must hold; optional fixed `filters` with `match: "all" | "any"` further narrow the matched records. No relation field is required. The catalog includes both standalone rollup and formula collection examples.

Submit the example with `flowbase formulas validate OBJECT --json-file query.json`. Include `fieldId` when editing an existing field. For a trial, use `trial: true` and a saved `recordId`; custom samples cannot trial collections. Validation requires metadata read; saved-record trials additionally require record read. Check `valid` and `trial.status`, then save valid constraints with `fields create/update`.

Matching uses saved current-record values. Empty matching inputs return `pending/matching_empty`; new records return `saved_required`. Successful authorized trials include collection parameters and candidate/matched counts. Full candidate permissions are checked before fixed filters; restricted results expose no totals or counts. Limits and timeouts never produce partial totals. See the catalog for compatible types, operators and budgets.

### Detail Page value assignments (4.22)

`flowbase docs catalogs page-value-rules` describes authoring and the edit sequence. Page snapshots support `setFieldValue` and `setDefaultFieldValue`; sources can traverse up to five single-record relations. `pages evaluate` continues to preview field states and component visibility only.

```bash
flowbase records get OBJECT RECORD
flowbase records page-value-context OBJECT RECORD
flowbase docs example records.page-value-event --output event.json
# Fill event.json with the returned pageId/revision, current edit delta,
# changed field IDs, and the preceding event's sources (initially {}).
flowbase records page-value-event OBJECT RECORD --json-file event.json
```

Context and event calls require both record read and write scopes, and do not save edits. Inspect `errors`, apply returned `values` to your edit delta, and carry `sources` into the next event's `previousSources`. Values use field keys, changed fields use IDs, and decimal assignments are returned as lossless strings. Defaults skip nonempty targets. Source/condition changes trigger assignment; simply reading or saving does not.

Save the merged edit delta with `records update`, including `pageId`, `valueRuleRevision` (the context's `revision`), and `updatedAt`. Configuration changes or stale record versions reject the save; reload and reconcile on 409. Page rules and field permissions are rechecked without rerunning assignments. Whole-record edits use the existing `bundle-save` / `configVersion` contract. Production context uses published configuration, while test Hosts use effective configuration.

### Official app store (4.14)

Read `flowbase docs catalogs app-store`. Reads and checks require metadata read; install, publish and listing changes require metadata write and confirmation (`--yes` in automation).

```bash
flowbase app-store context
flowbase app-store list --query tasks --page 1
flowbase app-store get PACKAGE
flowbase docs example app-store.install-check --output installation.json
# Set the reviewed version and desired app name.
flowbase app-store install-check PACKAGE --json-file installation.json
# Copy version/name into install.json; add the returned check and a fresh UUID request_id.
flowbase app-store install PACKAGE --json-file install.json --yes
flowbase app-store installation REQUEST_UUID
```

Installation requires a clean enabled environment and creates configuration drafts only. Review and release them separately. The check binds the current Host environment, source package, name, API key and authorization; it expires after 15 minutes. Changed inputs require another check. After a timeout, query the receipt before retrying; reuse a request ID only with the identical body. Inspect `status`/`error`, since HTTP success may report `processing` or `failed`. A failed attempt needs a new check and request ID.

For eligible official publishers on the production Host:

1. `app-store sources` discovers committed source apps; production drafts must be resolved first.
2. `app-store source-check --json '{"app_id":"APP"}'` returns a signed source snapshot.
3. `docs example app-store.publish-check --output publication.json` provides all required bilingual product fields. Fill them and the returned source, package ID and version, then run `app-store publish-check --json-file publication.json`.
4. Review product content and checked resources. Add `check`, a fresh UUID `request_id`, and `preview_confirmed: true`; run `app-store publish --json-file publish.json --yes`.
5. Query `app-store publication REQUEST_UUID` or `app-store publications`. Use `app-store listing PACKAGE --json '{"listed":false}' --yes` to withdraw, or `true` to relist.

Store request bodies use snake_case. `--yes` does not bypass publishing eligibility, production-only rules, portability validation or rechecks. These added commands need an updated CLI installation and a backend with the corresponding public routes; the package version is bumped separately during release.

### Reusable iframe configuration (4.11)

`flowbase iframes list|get|create|update|delete` manages environment-specific iframe drafts. Create/update use `--json-file`; fields are `label`, `icon` (default `IconWorld`), `color` (default `#2563EB`), and a complete HTTPS `url` without credentials. Update and delete require `baseRevision` from `iframes get`; deletion also requires confirmation (`--yes` for noninteractive use).

```bash
flowbase iframes create --json-file iframe.json
flowbase iframes get ifr_example
flowbase iframes update ifr_example --json-file iframe-update.json
flowbase apps add-iframes app_example ifr_example
flowbase apps set-iframe-group app_example ifr_example --group-id grp_example
flowbase apps set-iframe-group app_example ifr_example --ungrouped
flowbase apps reorder-members app_example --json '{"items":[{"type":"iframe","id":"ifr_example"}]}'
flowbase apps remove-iframe app_example ifr_example --yes
flowbase iframes delete ifr_example --json '{"baseRevision":12}' --yes
```

Removal only unlinks one app. Deletion unlinks all apps atomically. Changes follow the existing commit/release/rollback workflow; they do not fetch, proxy or modify the external website. API keys use `metadata:read`/`metadata:write`; browser roles use `iframe.manage` for shared resources and `app.manage` for app associations.

### Custom object views (4.12)

Read `flowbase docs catalogs custom-views` and `flowbase views list OBJECT` first. Save the following as `view.json`, replacing `baseRevision` with the current `draftRevision`:

```json
{
  "baseRevision": 4,
  "name": "Custom overview",
  "enabled": false,
  "defaultFieldIds": [],
  "displayMode": "custom",
  "custom": {
    "runtimeVersion": "cv1",
    "source": "import React from 'react'; export default function View(){return <div>Hello</div>}"
  }
}
```

```bash
flowbase views create obj_example --json-file view.json
flowbase views list obj_example
flowbase views update obj_example viw_example --json-file view.json
flowbase views set-enabled obj_example viw_example --base-revision 6 --enabled --yes
```

Use the revision returned by the preceding write, rather than the example numbers. Custom views start disabled; preview in the browser and enable when ready. Updates replace the writable snapshot: preserve `custom.source`, `custom.runtimeVersion`, `displayMode`, filters and other configuration from `views list`, excluding the response-only `id` and `status`. Built-in/custom view types cannot be converted. JSX source is limited to 512 KiB UTF-8; the runtime supports `react`, `three` and `flowbase`. CLI configuration does not execute browser previews.

### Record detail embedded pages (4.13)

`flowbase docs catalogs page-components` documents `recordEmbed`, supported at the top level or inside tabs of a detail Page. Add this component to an existing region column (or a tab's `components`):

```json
{
  "kind": "recordEmbed",
  "label": "External panel",
  "showTitle": true,
  "url": "https://example.com/panel",
  "height": 480,
  "allowRead": false,
  "allowedFieldIds": []
}
```

Read `flowbase pages get PAGE`, preserve the existing components and IDs, and remove the read-only Page keys listed in `docs catalogs page-components`. Wrap the editable snapshot as `{"baseRevision":4,"page":{...}}`, then use `flowbase pages update PAGE --json-file page.json` (or `pages create --json-file page.json` for a new detail Page). For creation, omit the Page ID and IDs of new regions/components so the server allocates them.

Height must be an integer from 240 to 1600. URLs must use external HTTPS and exclude credentials, identity/context parameters and templates. To permit SDK reads, set `allowRead: true` and select at least one unique active field ID in `allowedFieldIds`; current record/field permissions still apply. The browser SDK is `/sdk/record-embed.v1.js`. The CLI configures the component; rendering and SDK calls run in the browser. `flowbase-user` has no metadata management commands.
