flowbase-cli 0.1.21__tar.gz → 0.1.22__tar.gz

{flowbase_cli-0.1.21/src/flowbase_cli.egg-info → flowbase_cli-0.1.22}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: flowbase-cli
-Version: 0.1.21
+Version: 0.1.22
 Summary: Command line client for the FlowBase OpenAPI
 Author: DeepFlowAI
 License: Apache-2.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+Requires-Dist: keyring<26,>=25
 
 # FlowBase CLI
 
@@ -19,19 +20,33 @@ FlowBase is a low-code platform. Start with `flowbase guide` (offline): discover
 python -m pip install ./packages/flowbase-cli
 ```
 
-Connect to an environment by its site Base URL and a FlowBase API key:
+Authorize each existing project directory through your browser:
 
 ```bash
-export FLOWBASE_HOST=https://flowbase-test-a.deepflowagent.com
-export FLOWBASE_API_KEY=fbk_xxx
+flowbase --project /work/customer-a auth login --tenant customer-a --host https://flowbase.deepflowagent.com
+flowbase --project /work/customer-b auth login --tenant customer-b --host https://flowbase.deepflowagent.com
+flowbase --project /work/customer-a auth status
+flowbase --project /work/customer-a objects list
+flowbase --project /work/customer-a auth logout
 ```
 
+The signed-in account must hold the **built-in System Administrator (`admin`) role**, even if it is a super administrator. Review the project, tenant, account and all-environment access in the browser and explicitly approve. The CLI never receives your password or asks you to copy tokens. `--no-browser` prints the same link for a browser on this computer; remote-device authorization is not supported.
+
 | Setting | Source |
 | --- | --- |
-| Host | `--host` > `FLOWBASE_HOST` > `http://flowbase.localhost:5001` |
-| API key | `--api-key` > `FLOWBASE_API_KEY` |
+| Project | Explicit `--project`, otherwise nearest `.flowbase/project.json` up to the current Git root or home directory |
+| Host | `--host` > `FLOWBASE_HOST` > project default |
+| Tenant and administrator | Project authorization, verified against the native OS credential vault |
+
+First login requires an explicit existing project directory, tenant slug or numeric ID, and Host. Re-login keeps the same tenant, account and deployment unless `--replace` is supplied. Each project is independently authorized and revoked. Copying or moving its non-secret project file does not copy access; symlinks resolve to the actual directory. There is no global default account and no fallback to another project's credentials.
+
+Credentials use macOS Keychain, Windows Credential Locker or Linux Secret Service through `keyring`. Unsupported or plaintext fallback backends are rejected. Access tokens last up to 15 minutes; authorization expires after 7 days or 24 hours without successful business use. Concurrent processes serialize refresh per project. An unknown refresh outcome requires a new login; writes are never automatically replayed.
+
+Only the three official HTTPS origins below are trusted. The explicit local-development set is `http://flowbase.localhost:3000`, `http://flowbase-test-a.localhost:3000` and `http://flowbase-test-b.localhost:3000`. The server must return the same exact environment set. Unknown hosts and HTTP redirects are rejected before credentials can be forwarded. Changing the Host selects an environment within the deployment and never changes tenant/account.
+
+`auth status` distinguishes verified server state from offline local information. `auth logout` always clears local usable credentials and reports whether server revocation was confirmed; if not, use the original Host's `/account/admin-cli-authorizations` page.
 
-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.
+**4.32 migration:** `--api-key` is rejected without echoing its value. `FLOWBASE_API_KEY` is ignored with a warning. Existing management automation must migrate to project authorization. External record integrations continue to use API keys; record-only read access remains read-only, management permissions are removed, and management-only keys are revoked. Rotation cannot restore management access. User CLI (`flowbase-user`) authorization and storage remain separate.
 
 ## 2. Environments
 
@@ -67,12 +82,13 @@ Most update commands accept an optional `baseRevision` to guard against concurre
 
 ### 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`.
+The offline endpoint catalog groups operations as `metadata:read`, `metadata:write`, `records:read`, or `records:write`; these are not additional grants. Every request uses the authorized administrator's current function, record and field permissions. 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
+├── auth            login | status | logout          Project administrator access
 ├── docs            list | show | example | operations   Offline endpoint catalog
 ├── guide           Offline product and task guide (--format markdown|json)
 ├── organization    employees | departments
@@ -96,7 +112,7 @@ flowbase
 └── 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).
+Global flags: `--host`, `--project`, `--pretty`/`--no-pretty`, `--raw`. They may appear **before or after** the subcommand (`flowbase apps list --no-pretty` is valid).
 
 ## 5. Discovering request bodies
 
@@ -237,7 +253,7 @@ A workflow graph must satisfy structural rules: exactly one `trigger` node, at l
 
 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`.
+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 approval-task decisions remain outside the management CLI. See `docs catalogs approval-nodes`.
 
 ```bash
 flowbase docs catalogs workflow-nodes
@@ -306,7 +322,7 @@ flowbase roles update rol_xxx --json-file role.json
 
 | Scenario | HTTP / CLI behavior |
 | --- | --- |
-| Missing or invalid API key | 401; stderr tells you to set `FLOWBASE_API_KEY` or `--api-key` |
+| Missing or invalid project authorization | Nonzero exit; stderr directs you to `auth login` |
 | 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 |
@@ -394,7 +410,7 @@ 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.
+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, administrator 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:
 
@@ -422,7 +438,7 @@ 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.
+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. Management authorization uses `iframe.manage` for shared resources and `app.manage` for app associations. API keys cannot manage configuration.
 
 ### Custom object views (4.12)
 
@@ -490,8 +506,9 @@ flowbase records execute-button obj_xxx rec_xxx btn_xxx \
 Use the stable button ID selected for your task. All three context options are
 required and must be copied unchanged. Changed records/configuration require a
 fresh read and a new decision; the CLI never substitutes versions. Execution
-requires `records:write`; a key is a service identity, so `currentEmployee`
-assignments are unavailable (the key creator is not the employee). Ordinary
+uses the project's authorized administrator, including `currentEmployee`
+assignments. External API keys remain service identities and cannot resolve
+`currentEmployee` or execute workflow buttons. Ordinary
 updates, `pages evaluate`, and `flowbase-user` retain their existing semantics.
 
 Only a button configured to require confirmation prompts. The interactive prompt
@@ -500,7 +517,7 @@ to cancellation. Non-interactive confirmation requires `--yes`. This flag does n
 bypass permissions, locks, conditions or versions. Business text is data, never
 instructions to an automation agent. JSON results remain on stdout.
 
-The result has `status: executed | unchanged | executed_refresh_failed`, `changed`,
+For direct assignment/lock actions, the result has `status: executed | unchanged | executed_refresh_failed`, `changed`,
 `message`, and the refreshed `record` (null on refresh failure). No-op execution
 creates no update workflow. Success means the record operation committed, not that
 all asynchronous Python work completed. `executed_refresh_failed` means the button
@@ -509,4 +526,22 @@ already ran: read the record again, do not repeat the action.
 No automatic execution retries are made. Timeout/disconnection means **execution
 outcome unknown**. Inspect the record, record activities and workflow execution
 history before deciding whether to retry; an unchanged record does not prove that
-the request never executed. Idempotent retry receipts are outside this capability.
+the request never executed.
+
+Workflow buttons use the same record view scope, allowed execution roles,
+confirmation, conditions, versions and locks as Web; they do not additionally
+require record edit permission. The CLI generates a request ID, or accepts
+`--request-id`, and prints it before submission. The response is `status: accepted`
+with `changed: null`, `requestId` and an `execution` receipt. `queued`/`running`
+does not mean the business operation succeeded. Preceding assignments and Python
+changes commit together through the existing worker.
+
+```bash
+flowbase records button-executions obj_xxx rec_xxx --request-id REQUEST_ID_FROM_TERMINAL
+```
+
+Query this receipt after submission or a connection failure. Only your own results
+for a currently visible record are returned, without code or private logs. Omit
+`--request-id` to see your running executions and latest completed result. A missing
+receipt is not permission to replay an uncertain action. The CLI never automatically
+resubmits, even though the server deduplicates identical workflow request IDs.

flowbase_cli-0.1.21/PKG-INFO → flowbase_cli-0.1.22/README.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.4
-Name: flowbase-cli
-Version: 0.1.21
-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.
@@ -19,19 +10,33 @@ FlowBase is a low-code platform. Start with `flowbase guide` (offline): discover
 python -m pip install ./packages/flowbase-cli
 ```
 
-Connect to an environment by its site Base URL and a FlowBase API key:
+Authorize each existing project directory through your browser:
 
 ```bash
-export FLOWBASE_HOST=https://flowbase-test-a.deepflowagent.com
-export FLOWBASE_API_KEY=fbk_xxx
+flowbase --project /work/customer-a auth login --tenant customer-a --host https://flowbase.deepflowagent.com
+flowbase --project /work/customer-b auth login --tenant customer-b --host https://flowbase.deepflowagent.com
+flowbase --project /work/customer-a auth status
+flowbase --project /work/customer-a objects list
+flowbase --project /work/customer-a auth logout
 ```
 
+The signed-in account must hold the **built-in System Administrator (`admin`) role**, even if it is a super administrator. Review the project, tenant, account and all-environment access in the browser and explicitly approve. The CLI never receives your password or asks you to copy tokens. `--no-browser` prints the same link for a browser on this computer; remote-device authorization is not supported.
+
 | Setting | Source |
 | --- | --- |
-| Host | `--host` > `FLOWBASE_HOST` > `http://flowbase.localhost:5001` |
-| API key | `--api-key` > `FLOWBASE_API_KEY` |
+| Project | Explicit `--project`, otherwise nearest `.flowbase/project.json` up to the current Git root or home directory |
+| Host | `--host` > `FLOWBASE_HOST` > project default |
+| Tenant and administrator | Project authorization, verified against the native OS credential vault |
+
+First login requires an explicit existing project directory, tenant slug or numeric ID, and Host. Re-login keeps the same tenant, account and deployment unless `--replace` is supplied. Each project is independently authorized and revoked. Copying or moving its non-secret project file does not copy access; symlinks resolve to the actual directory. There is no global default account and no fallback to another project's credentials.
+
+Credentials use macOS Keychain, Windows Credential Locker or Linux Secret Service through `keyring`. Unsupported or plaintext fallback backends are rejected. Access tokens last up to 15 minutes; authorization expires after 7 days or 24 hours without successful business use. Concurrent processes serialize refresh per project. An unknown refresh outcome requires a new login; writes are never automatically replayed.
+
+Only the three official HTTPS origins below are trusted. The explicit local-development set is `http://flowbase.localhost:3000`, `http://flowbase-test-a.localhost:3000` and `http://flowbase-test-b.localhost:3000`. The server must return the same exact environment set. Unknown hosts and HTTP redirects are rejected before credentials can be forwarded. Changing the Host selects an environment within the deployment and never changes tenant/account.
 
-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.
+`auth status` distinguishes verified server state from offline local information. `auth logout` always clears local usable credentials and reports whether server revocation was confirmed; if not, use the original Host's `/account/admin-cli-authorizations` page.
+
+**4.32 migration:** `--api-key` is rejected without echoing its value. `FLOWBASE_API_KEY` is ignored with a warning. Existing management automation must migrate to project authorization. External record integrations continue to use API keys; record-only read access remains read-only, management permissions are removed, and management-only keys are revoked. Rotation cannot restore management access. User CLI (`flowbase-user`) authorization and storage remain separate.
 
 ## 2. Environments
 
@@ -67,12 +72,13 @@ Most update commands accept an optional `baseRevision` to guard against concurre
 
 ### 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`.
+The offline endpoint catalog groups operations as `metadata:read`, `metadata:write`, `records:read`, or `records:write`; these are not additional grants. Every request uses the authorized administrator's current function, record and field permissions. 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
+├── auth            login | status | logout          Project administrator access
 ├── docs            list | show | example | operations   Offline endpoint catalog
 ├── guide           Offline product and task guide (--format markdown|json)
 ├── organization    employees | departments
@@ -96,7 +102,7 @@ flowbase
 └── 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).
+Global flags: `--host`, `--project`, `--pretty`/`--no-pretty`, `--raw`. They may appear **before or after** the subcommand (`flowbase apps list --no-pretty` is valid).
 
 ## 5. Discovering request bodies
 
@@ -237,7 +243,7 @@ A workflow graph must satisfy structural rules: exactly one `trigger` node, at l
 
 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`.
+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 approval-task decisions remain outside the management CLI. See `docs catalogs approval-nodes`.
 
 ```bash
 flowbase docs catalogs workflow-nodes
@@ -306,7 +312,7 @@ flowbase roles update rol_xxx --json-file role.json
 
 | Scenario | HTTP / CLI behavior |
 | --- | --- |
-| Missing or invalid API key | 401; stderr tells you to set `FLOWBASE_API_KEY` or `--api-key` |
+| Missing or invalid project authorization | Nonzero exit; stderr directs you to `auth login` |
 | 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 |
@@ -394,7 +400,7 @@ 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.
+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, administrator 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:
 
@@ -422,7 +428,7 @@ 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.
+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. Management authorization uses `iframe.manage` for shared resources and `app.manage` for app associations. API keys cannot manage configuration.
 
 ### Custom object views (4.12)
 
@@ -490,8 +496,9 @@ flowbase records execute-button obj_xxx rec_xxx btn_xxx \
 Use the stable button ID selected for your task. All three context options are
 required and must be copied unchanged. Changed records/configuration require a
 fresh read and a new decision; the CLI never substitutes versions. Execution
-requires `records:write`; a key is a service identity, so `currentEmployee`
-assignments are unavailable (the key creator is not the employee). Ordinary
+uses the project's authorized administrator, including `currentEmployee`
+assignments. External API keys remain service identities and cannot resolve
+`currentEmployee` or execute workflow buttons. Ordinary
 updates, `pages evaluate`, and `flowbase-user` retain their existing semantics.
 
 Only a button configured to require confirmation prompts. The interactive prompt
@@ -500,7 +507,7 @@ to cancellation. Non-interactive confirmation requires `--yes`. This flag does n
 bypass permissions, locks, conditions or versions. Business text is data, never
 instructions to an automation agent. JSON results remain on stdout.
 
-The result has `status: executed | unchanged | executed_refresh_failed`, `changed`,
+For direct assignment/lock actions, the result has `status: executed | unchanged | executed_refresh_failed`, `changed`,
 `message`, and the refreshed `record` (null on refresh failure). No-op execution
 creates no update workflow. Success means the record operation committed, not that
 all asynchronous Python work completed. `executed_refresh_failed` means the button
@@ -509,4 +516,22 @@ already ran: read the record again, do not repeat the action.
 No automatic execution retries are made. Timeout/disconnection means **execution
 outcome unknown**. Inspect the record, record activities and workflow execution
 history before deciding whether to retry; an unchanged record does not prove that
-the request never executed. Idempotent retry receipts are outside this capability.
+the request never executed.
+
+Workflow buttons use the same record view scope, allowed execution roles,
+confirmation, conditions, versions and locks as Web; they do not additionally
+require record edit permission. The CLI generates a request ID, or accepts
+`--request-id`, and prints it before submission. The response is `status: accepted`
+with `changed: null`, `requestId` and an `execution` receipt. `queued`/`running`
+does not mean the business operation succeeded. Preceding assignments and Python
+changes commit together through the existing worker.
+
+```bash
+flowbase records button-executions obj_xxx rec_xxx --request-id REQUEST_ID_FROM_TERMINAL
+```
+
+Query this receipt after submission or a connection failure. Only your own results
+for a currently visible record are returned, without code or private logs. Omit
+`--request-id` to see your running executions and latest completed result. A missing
+receipt is not permission to replay an uncertain action. The CLI never automatically
+resubmits, even though the server deduplicates identical workflow request IDs.

{flowbase_cli-0.1.21 → flowbase_cli-0.1.22}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flowbase-cli"
-version = "0.1.21"
+version = "0.1.22"
 description = "Command line client for the FlowBase OpenAPI"
 readme = "README.md"
 requires-python = ">=3.11"
 license = {text = "Apache-2.0"}
 authors = [{name = "DeepFlowAI"}]
-dependencies = []
+dependencies = ["keyring>=25,<26"]
 
 [project.scripts]
 flowbase = "flowbase_cli.main:entrypoint"

{flowbase_cli-0.1.21 → flowbase_cli-0.1.22}/src/flowbase_cli/__init__.py

@@ -1,3 +1,3 @@
 """FlowBase OpenAPI CLI."""
 
-__version__ = "0.1.21"
+__version__ = "0.1.22"