buildify-cli 1.0.0__py3-none-any.whl

buildify_cli/credential_form.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+UI_ONLY = frozenset({"Space", "TestButton"})
+SECRET_UI = frozenset({"Password"})
+
+CREDENTIAL_INPUT_REQUIRED = "credential_input_required"
+
+
+def default_credential_name(bundle_name: str, type_name: str) -> str:
+    """Machine-safe instance name. Agent must display this and wait for confirmation."""
+    slug = (bundle_name or "").split("/")[-1].strip().lower()
+    slug = re.sub(r"[^a-z0-9]+", "-", slug).strip("-")
+    if slug:
+        return slug
+    fallback = re.sub(r"[^a-z0-9]+", "-", (type_name or "").lower()).strip("-")
+    return fallback or "credential"
+
+
+def default_credential_label(type_label: Optional[str], type_name: str) -> str:
+    label = (type_label or "").strip()
+    return label or (type_name or "").strip() or "访问凭证"
+
+
+def is_secret_field(field: dict[str, Any]) -> bool:
+    ui = str(field.get("uiComponent") or "")
+    if ui in SECRET_UI:
+        return True
+    options = field.get("typeOptions")
+    if isinstance(options, dict):
+        if options.get("password") is True:
+            return True
+        if str(options.get("type") or "").lower() == "password":
+            return True
+    return False
+
+
+def form_fields(schema: Any) -> list[dict[str, Any]]:
+    """Leaf credential form fields (skip TestButton / _prefixed)."""
+    if not isinstance(schema, dict):
+        return []
+    properties = schema.get("properties")
+    if not isinstance(properties, list):
+        return []
+    out: list[dict[str, Any]] = []
+    for raw in properties:
+        if not isinstance(raw, dict):
+            continue
+        name = str(raw.get("name") or "").strip()
+        if not name or name.startswith("_"):
+            continue
+        ui = str(raw.get("uiComponent") or "")
+        if ui in UI_ONLY:
+            continue
+        out.append(
+            {
+                "name": name,
+                "label": str(raw.get("label") or name),
+                "required": bool(raw.get("required")),
+                "secret": is_secret_field(raw),
+                "uiComponent": ui or None,
+                "placeholder": raw.get("placeholder"),
+                "default": raw.get("default"),
+            }
+        )
+    return out
+
+
+def user_message(
+    *,
+    project_name: str,
+    bundle_name: str,
+    type_name: str,
+    type_label: str,
+    default_name: str,
+    default_label: str,
+    fields: list[dict[str, Any]],
+    missing: list[str],
+) -> str:
+    lines = [
+        "创建访问凭证前需要你确认项目，并提供表单参数。",
+        "",
+        f"项目：{project_name}",
+        f"软件包：{bundle_name}",
+        f"类型：{type_label or type_name}（{type_name}）",
+        "",
+        "建议的名称（可改，确认前不会创建）：",
+        f"  - name（引用名）：{default_name}",
+        f"  - label（显示名）：{default_label}",
+        "",
+        "请提供以下参数（密钥类字段不会被回显）：",
+    ]
+    if not fields:
+        lines.append("  （该类型没有表单字段）")
+    for field in fields:
+        flag = "必填" if field.get("required") else "可选"
+        secret = "，密钥" if field.get("secret") else ""
+        lines.append(f"  - {field['label']}（{field['name']}，{flag}{secret}）")
+    if missing:
+        lines.append("")
+        lines.append("还缺：" + "、".join(missing))
+    lines.extend(
+        [
+            "",
+            "请确认或修改 name / label，并给出参数值。确认后再创建。",
+            "不要把密钥写进仓库或命令行参数；用 stdin：",
+            "  printf '%s' '{\"host\":\"...\"}' | buildify --json project create-credential \\",
+            "    -p <项目> -b <bundle> --type <类型> --name <name> --label <label> --file -",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def prompt_payload(
+    *,
+    project_id: str,
+    project_name: str,
+    bundle_name: str,
+    bundle_version: Optional[str],
+    type_name: str,
+    type_label: str,
+    default_name: str,
+    default_label: str,
+    fields: list[dict[str, Any]],
+    missing: list[str],
+) -> dict[str, Any]:
+    return {
+        "reason": CREDENTIAL_INPUT_REQUIRED,
+        "projectId": project_id,
+        "projectName": project_name,
+        "bundleName": bundle_name,
+        "bundleVersion": bundle_version,
+        "type": type_name,
+        "typeLabel": type_label,
+        "defaults": {"name": default_name, "label": default_label},
+        "missing": missing,
+        "parameters": fields,
+        "userMessage": user_message(
+            project_name=project_name,
+            bundle_name=bundle_name,
+            type_name=type_name,
+            type_label=type_label,
+            default_name=default_name,
+            default_label=default_label,
+            fields=fields,
+            missing=missing,
+        ),
+        "agentInstructions": (
+            "Stop. Show data.userMessage (includes default name/label). Ask the user to "
+            "confirm or change name/label and to provide parameter values. Do not create "
+            "until they confirm. Then POST via stdin --file - ; never echo secrets, never "
+            "pass --data on argv, never write secrets into the repo."
+        ),
+    }

buildify_cli/exit_codes.py

@@ -0,0 +1,8 @@
+"""Stable exit codes for scripts and AI agents (same scheme as buildify-publish)."""
+
+OK = 0
+GENERIC = 1
+AUTH_CONFIG = 2
+LOCAL_VALIDATION = 3
+SERVER_CLIENT_ERROR = 4
+NETWORK = 5

buildify_cli/output.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Optional, TextIO
+
+SUCCESS_BODY_CODE = 200
+
+
+def is_tty(stream: TextIO) -> bool:
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def os_no_color() -> bool:
+    return os.environ.get("NO_COLOR", "").strip() != ""
+
+
+def print_json(
+    *,
+    ok: bool,
+    code: int,
+    msg: str,
+    http_status: int,
+    data: Any = None,
+    stream: Optional[TextIO] = None,
+) -> None:
+    payload = {
+        "ok": ok,
+        "code": code,
+        "msg": msg,
+        "http_status": http_status,
+        "data": data,
+    }
+    out = sys.stdout if stream is None else stream
+    out.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    out.flush()
+
+
+def human_err(message: str) -> None:
+    sys.stderr.write(message + "\n")
+    sys.stderr.flush()
+
+
+def body_success(code: Optional[int]) -> bool:
+    return code is None or code == SUCCESS_BODY_CODE

buildify_cli/publish_view.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+_STATUS_ICON = {
+    "success": "✅",
+    "success_with_warnings": "⚠️",
+    "failed": "❌",
+    "timeout": "⏰",
+    "running": "🔄",
+    "canceled": "🚫",
+    "pending": "⏳",
+}
+
+_STATUS_TITLE = {
+    "success": "已发布",
+    "success_with_warnings": "已发布（有警告）",
+    "failed": "发布失败",
+    "timeout": "发布超时",
+    "running": "发布中",
+    "canceled": "已取消",
+    "pending": "发布中",
+}
+
+_STATUS_LABEL = {
+    "success": "成功",
+    "success_with_warnings": "成功（有警告）",
+    "failed": "失败",
+    "timeout": "超时",
+    "running": "部署中",
+    "canceled": "已取消",
+    "pending": "待部署",
+}
+
+
+def is_publish_payload(payload: Any) -> bool:
+    return isinstance(payload, dict) and isinstance(payload.get("summary"), dict)
+
+
+def format_publish_report(payload: dict[str, Any]) -> str:
+    """Markdown tables + status icons for deploy / published / deployment responses."""
+    summary = payload.get("summary") or {}
+    status = _status_key(payload.get("deployStatus"))
+    icon = payload.get("deployStatusIcon") or _STATUS_ICON.get(status, "⏳")
+    label = payload.get("deployStatusLabel") or _STATUS_LABEL.get(status, "待部署")
+    title = _STATUS_TITLE.get(status, "发布")
+
+    project = _cell(summary.get("projectName"))
+    workflow = _cell(summary.get("workflowName"))
+    version = summary.get("versionName") or payload.get("versionName") or "—"
+    publish_remark = summary.get("publishRemark") or payload.get("publishRemark") or "—"
+    published_at = payload.get("publishedAt") or payload.get("createdAt") or "—"
+
+    lines: list[str] = [
+        f"## {icon} {title}",
+        "",
+        "| 项 | 内容 |",
+        "| --- | --- |",
+        f"| 项目 | {project} |",
+        f"| 流程 | {workflow} |",
+        f"| 版本号 | `{_cell(version)}` |",
+        f"| 发布说明 | {_cell(publish_remark)} |",
+        f"| 总体 | {icon} {label} |",
+    ]
+    if published_at and published_at != "—":
+        lines.append(f"| 发布时间 | {published_at} |")
+
+    servers = summary.get("servers") or []
+    lines.extend(["", "### 服务器", ""])
+    if servers:
+        lines.append("| 服务器 | 描述 | 在线 | 部署 | 说明 |")
+        lines.append("| --- | --- | --- | --- | --- |")
+        for server in servers:
+            if not isinstance(server, dict):
+                continue
+            online = bool(server.get("isOnline"))
+            online_icon = server.get("onlineIcon") or ("🟢" if online else "⚫")
+            online_label = server.get("onlineLabel") or ("在线" if online else "离线")
+            st = _status_key(server.get("deployStatus"))
+            st_icon = server.get("deployStatusIcon") or _STATUS_ICON.get(st, "⏳")
+            st_label = server.get("deployStatusLabel") or _STATUS_LABEL.get(st, "待部署")
+            remark = server.get("remark") or "无描述"
+            message = server.get("message") or "—"
+            lines.append(
+                f"| {_cell(server.get('workerName'))} | {_cell(remark)} | "
+                f"{online_icon} {online_label} | {st_icon} {st_label} | {_cell(message)} |"
+            )
+    else:
+        lines.append("*未绑定服务器*")
+
+    creds = summary.get("credentials") or []
+    lines.extend(["", "### 凭证", ""])
+    if creds:
+        lines.append("| Bundle | 类型 | name | 名称 |")
+        lines.append("| --- | --- | --- | --- |")
+        for cred in creds:
+            if not isinstance(cred, dict):
+                continue
+            lines.append(
+                f"| {_cell(cred.get('bundleName'))} | {_cell(cred.get('type'))} | "
+                f"{_cell(cred.get('name'))} | {_cell(cred.get('label'))} |"
+            )
+    else:
+        lines.append("*本流程未引用访问凭证*")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _status_key(value: Any) -> str:
+    if value is None:
+        return "pending"
+    if isinstance(value, str):
+        return value.strip().lower() or "pending"
+    name = getattr(value, "name", None)
+    if isinstance(name, str):
+        return name.strip().lower()
+    return str(value).strip().lower() or "pending"
+
+
+def _cell(value: Optional[Any]) -> str:
+    text = "—" if value is None or str(value).strip() == "" else str(value).strip()
+    return text.replace("|", "\\|").replace("\n", " ")

buildify_cli/usage.md

@@ -0,0 +1,245 @@
+# Buildify open API CLI — quick reference
+
+Authoring workflows from a terminal: discover installed bundle nodes, read their form schemas
+and docs, reference existing credentials, then create / validate / test run / deploy a flow.
+
+**Default API base URL:** `https://openapi.buildify.cn` (override with `--base-url` or `BUILDIFY_OPENAPI_BASE_URL`).
+
+**Auth:** `Authorization: Bearer <keyId>.<secret>`. Keys are **issued and revoked in the console**
+(workspace settings → Open API keys), not via this CLI. One key is bound to exactly one workspace;
+every command below is implicitly scoped to it. The plaintext is shown **only once** at creation.
+
+If no key is configured:
+
+- **TTY** (not `--json`): print how to create the key, hidden-prompt for it, save to `~/.buildifyrc`
+  with mode `600`, then continue.
+- **`--json` / CI / pipe:** exit 2. JSON `data.reason` is `missing_api_key`; `data.userMessage` is
+  the Chinese how-to; `data.agentInstructions` tells agents to ask the user and save via stdin.
+
+Several workspaces mean several keys. Save each with `config add-profile <name>` (this does **not**
+change the default). A repo may commit `.buildify-workspace` containing only the public workspace id
+from `key test` (`tenantId`) — never a secret.
+
+Selection order: `--api-key` / `BUILDIFY_OPENAPI_API_KEY`, then `--profile` / `BUILDIFY_OPENAPI_PROFILE`,
+then `.buildify-workspace`, then `[openapi].current`, then the only saved key. If more than one key
+matches and none of those picked one, exit 2 with `data.reason=profile_required` and a list that has
+no secrets. Agents show that list, ask once, then pass `--profile <name>` on later commands. Do **not**
+run `config use` unless the user asked to change the default workspace. A pin with no matching local
+key exits 2 with `data.reason=workspace_key_missing`.
+
+**Do not** pass `--api-key` or the secret as an argv token (process list / shell history). Prefer
+`buildify config add-profile <name>` (hidden prompt) or:
+
+```bash
+printf '%s' 'keyId.secret' | buildify config add-profile acme
+```
+
+`config set-key api_key` still writes the current profile, or the legacy `[openapi].api_key` when no
+current profile is set. Never write the key into the project tree, a committed `.env`, issues, or chat
+replies. After save, only display the masked value from `config show` or `config profiles`. A project
+404 includes `tenantId` and `profile` so a miss can be a wrong workspace rather than a missing project.
+
+**Out of scope:** creating OpenAPI keys. Credentials are created with `project create-credential` after
+the user confirms project, name/label and form values. Publish with `workflow deploy` after the test run passes.
+
+## Environment variables
+
+| Variable | Meaning |
+|----------|---------|
+| `BUILDIFY_OPENAPI_BASE_URL` | API root (no trailing slash) |
+| `BUILDIFY_OPENAPI_API_KEY` | Full Bearer secret `keyId.secret` (ignores profiles) |
+| `BUILDIFY_OPENAPI_PROFILE` | Profile name; same as `--profile` |
+| `BUILDIFY_OPENAPI_JSON` | If `1`/`true`/`yes`, same as global `--json` |
+| `BUILDIFY_OPENAPI_NO_PROMPT` | If `1`/`true`/`yes`, never prompt for a missing key |
+| `NO_COLOR` | Disable ANSI colors |
+
+**Config file:** `~/.buildifyrc`, section `[openapi]`: `base_url`, legacy `api_key`, `current`, and
+`profiles.<name>` (`api_key`, cached `tenant_id` / `key_name` / `key_prefix`). File mode `600`.
+Shared with `buildify-publish`, which uses the top-level keys — the two do not collide.
+
+**Precedence:** `--api-key` / `BUILDIFY_OPENAPI_API_KEY` > `--profile` / `BUILDIFY_OPENAPI_PROFILE` >
+`.buildify-workspace` > `[openapi].current` > the only saved key > `profile_required` or `missing_api_key`.
+Base URL: CLI flag > `BUILDIFY_OPENAPI_BASE_URL` > file > default.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Generic failure |
+| 2 | Missing config/auth or HTTP 401/403 |
+| 3 | Local validation (bad JSON, file not found) |
+| 4 | HTTP 4xx/5xx, **or `workflow validate` found errors** |
+| 5 | Network / timeout / connection error |
+
+## Commands → HTTP
+
+All paths are under `/openapi/v1`.
+
+| CLI | Method | Path |
+|-----|--------|------|
+| `health` | GET | `/health` (no auth) |
+| `key test` | GET | `/key/test` |
+| `bundle list` | GET | `/bundles` |
+| `bundle nodes` | GET | `/bundles/nodes` — flattened catalog (`icon`/`label`/`isTrigger` from `groups_json` + `nodes_json`) |
+| `bundle node-properties` | GET | `/bundles/nodes/properties` |
+| `bundle node-relations` | GET | `/bundles/nodes/relations` |
+| `bundle doc` | GET | `/bundles/doc` |
+| `bundle cred-types` | GET | `/bundles/credentials/types` |
+| `bundle cred-properties` | GET | `/bundles/credentials/properties` |
+| `project list` / `create` / `get` | GET / POST / GET | `/projects[...]` |
+| `project credentials` | GET | `/projects/{id}/credentials` |
+| `project create-credential` | POST | `/projects/{id}/credentials` |
+| `project workers` | GET | `/projects/{id}/workers` |
+| `workflow list` / `create` | GET / POST | `/projects/{id}/workflows` |
+| `workflow get-draft` / `save-draft` | GET / POST | `/projects/{id}/workflows/{wid}/draft` |
+| `workflow validate` | POST | `/projects/{id}/workflows/validate` |
+| `workflow test-run` | POST | `/projects/{id}/workflows/test_runs` |
+| `workflow cancel-test` | POST | `/projects/{id}/workflows/test_runs/{executionId}/cancel` |
+| `workflow deploy` | POST | `/projects/{id}/workflows/{wid}/deploy` |
+| `workflow published` | GET | `/projects/{id}/workflows/{wid}/published` |
+| `workflow deployment` | GET | `/projects/{id}/workflows/{wid}/deployments/{deployId}` |
+
+## Typical session
+
+```bash
+# 0. one-time config (prefer stdin; never put the secret on argv)
+printf '%s' 'keyId.secret' | buildify config add-profile acme
+buildify config set-key base_url https://openapi.buildify.cn
+buildify --json key test
+buildify --json config profiles          # no secrets; ask the user if reason=profile_required
+# missing key + --json → exit 2, data.reason=missing_api_key; ask the user, then save via stdin
+
+# 1. where does this flow live, and which worker runs it
+buildify --json project list
+buildify --json project workers -p proj_xxx --online-only
+
+# 2. what can I build with
+buildify --json bundle list
+buildify --json bundle nodes -b official/core
+buildify --json bundle node-properties -b official/core -n WebhookTrigger
+buildify --json bundle node-relations  -b official/core -n WebhookTrigger
+buildify bundle doc -b official/core            # Markdown usage document
+
+# 3. which credentials may the flow reference (secrets are never returned)
+buildify --json project credentials -p proj_xxx
+# missing name/label/data → exit 3 with defaults + form fields; show them, wait, then:
+printf '%s' '{"host":"example.com","password":"…"}' | buildify --json project create-credential \
+  -p proj_xxx -b official/core --type Mysql --name mysql --label "生产只读" --file -
+
+# 4. author flow.json locally, then loop until it is clean
+buildify --json workflow validate -p proj_xxx -f ./flow.json
+
+# 5. land it and try it
+buildify --json workflow create -p proj_xxx -n "订单同步" --worker wk_xxx
+buildify --json workflow save-draft -p proj_xxx -w wf_xxx -f ./flow.json
+buildify --json workflow test-run   -p proj_xxx -f ./flow.json --worker wk_xxx --timeout 60
+buildify --json workflow deploy     -p proj_xxx -w wf_xxx --worker wk_xxx \
+  --version-name "v1.0.0" --remark "首次上线" --wait
+```
+
+`--file -` reads JSON from stdin (flow canvas or credential `data`).
+
+## project create-credential
+
+Requires `--project`. Also pass `--bundle` and `--type`. If `--name` / `--label` / credential
+`--file` are omitted:
+
+- **TTY:** show default name/label, prompt for form fields (password hidden), then confirm.
+- **`--json`:** exit 3, `data.reason=credential_input_required`. `defaults` and `userMessage`
+  include the suggested name/label; `parameters` lists form fields (`secret: true` for secrets).
+  Agents must display those defaults, wait for confirmation and values, then create via stdin.
+  Never echo secrets; never pass `--data` on argv.
+
+Response is metadata only (`name` / `label` / `type` / `credentialsId`). Duplicate
+`bundle+type+name` in the same project returns HTTP 409.
+
+## Version conflicts on save-draft
+
+`workflow save-draft` reads the current draft to obtain the optimistic-lock `version` unless you pass
+`--version`. If someone edited the flow in the console in between, the server returns a conflict
+(exit 4) and the response `data` carries the latest draft — re-apply your changes on top of it
+rather than retrying blindly.
+
+## workflow validate
+
+Checks, in this order: canvas structure, node existence in the workspace, `data.parameters`
+against each node's `properties_json`, `edges[].data.relations[].name` against the source node's
+`relations_json` (or the source node's custom `data.relations` for MCP), `data.credentials`
+against the project's credentials, graph shape (trigger present, orphan nodes, cycles),
+and WARNINGs if catalog `icon` is missing on a node or an edge relation is missing `label` /
+custom `icon`/`_id`.
+
+Response `data`:
+
+```json
+{
+  "valid": false,
+  "errorCount": 1,
+  "warningCount": 2,
+  "issues": [
+    {"level": "ERROR", "nodeId": "n2", "path": "data.parameters.url", "message": "缺少必填参数: url"}
+  ]
+}
+```
+
+`valid: false` exits 4 even though HTTP is 200, so `until buildify workflow validate ...; do ...; done`
+works as a loop condition.
+
+## workflow test-run
+
+Submits the flow to a worker and **blocks** until it finishes, then returns the aggregated result.
+Node outputs are collected server-side from the execution event stream, so no WebSocket handling
+is needed on the client.
+
+Response `data`: `success`, `reason`, `executionId`, `nodes[]` (per node: `nodeId`, `status`,
+`outputs[]` with `relation` + `payload`, `error`), and `events[]` in arrival order.
+
+`--start-node` runs a single node instead of the whole graph. `--timeout` defaults to the server's
+60s; the HTTP read timeout is set to `timeout + 30s`. On timeout the partial result is returned with
+`reason: "timeout"` — use `workflow cancel-test` with the returned `executionId` to stop the worker.
+
+## workflow deploy / published / deployment
+
+`workflow deploy` promotes the **already saved draft** (omit `--file` after `save-draft`). `--worker` is
+required and must already be bound to the flow. At publish time set:
+
+- `--version-name` — version label written on this release (e.g. `v1.0.0`). Omit to let the server
+  generate `vyyyyMMdd-HHmmss`.
+- `--remark` — release note on this version only (not the workflow's description). Omit for none.
+
+Passing `--file` re-uploads canvas JSON and then needs `--version` or a draft fetch; don't do that
+in the normal authoring loop.
+
+Default `--wait` polls `GET .../deployments/{id}?statusOnly=true` (status + per-server result only)
+until `deployStatus` is terminal, then does **one** full GET for the summary tables. Failures exit 4.
+`--no-wait` returns immediately with `deploymentId` still `pending`.
+
+Do **not** call `workflow published` right after a successful `--wait`; the wait response already has
+`summary`. Use `workflow published` later to ask what is live.
+
+`data.summary` (also returned by `workflow published`) is the human/agent report:
+
+- `projectName`, `workflowName`, `versionName`, `publishRemark`
+- overall `deployStatus` + `deployStatusIcon` (`✅`/`⚠️`/`❌`/`⏳`/…) + `deployStatusLabel`
+- `servers[]`: `workerName`, `remark`, `isOnline`, `onlineIcon` (`🟢`/`⚫`), `onlineLabel`,
+  `deployStatus`, `deployStatusIcon`, `deployStatusLabel`, `message`
+- `nodes[]`: `label` / `summary` / `isTrigger` / `webhookPath`（JSON 仍返回；人读报告不打印节点表）
+- `credentials[]`: `bundleName` / `type` / `name` / `label` (never secrets)
+- `bundles[]`
+
+Without `--json`, `workflow deploy` / `published` / `deployment` print Markdown tables with those icons
+（项目 / 服务器 / 凭证；凭证表含 `name` 与 `label`，不含节点表）。
+With `--json`, agents should render the same tables (see buildify-flow-dev skill).
+
+`workflow published` is the live snapshot after deploy. `workflow deployment -d deploy_…` is one attempt.
+
+## JSON output schema
+
+With `--json`, stdout is exactly one JSON object per invocation:
+
+```json
+{"ok": true, "code": 200, "msg": "...", "http_status": 200, "data": {}}
+```
+
+`data` matches the server `R.data` field.

buildify_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: buildify-cli
+Version: 1.0.0
+Summary: CLI for the Buildify open API: discover bundle nodes, author and test workflows (machine Bearer auth)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Requires-Dist: tomli-w<2,>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# buildify-cli
+
+CLI for the Buildify **open API** (`buildify-open-api-server`): discover installed bundle nodes,
+read their form schemas and documentation, reference workspace credentials, and create, validate,
+test run and deploy workflows — all with a machine API key, no browser session.
+
+`workflow deploy` publishes a draft to workers that are already bound to the flow. It does not pick
+servers. Credentials can be created with `project create-credential` after the user confirms
+the project, name/label and form values.
+
+For publishing bundle JARs see the sibling [buildify-publish-cli](../buildify-publish-cli).
+
+## Install
+
+```bash
+pip install buildify-cli      # or pipx / uv tool install
+buildify help                 # full Markdown reference on stdout
+```
+
+Requires Python 3.10+.
+
+## Configure
+
+Create a key in the console (workspace settings → Open API keys). The full `keyId.secret` is shown
+**only once**. One key belongs to one workspace. Save each workspace under its own profile:
+
+```bash
+printf '%s' 'keyId.secret' | buildify config add-profile acme
+buildify config set-key base_url https://openapi.buildify.cn
+buildify --json key test
+buildify --json config profiles
+```
+
+`add-profile` does not change the default. `config use <name>` does, for a person at the terminal.
+Agents should pass `--profile <name>` instead. A repo may commit `.buildify-workspace` with only the
+public workspace id (`tenantId` from `key test`).
+
+If a command runs with no key: a TTY prompts and saves locally; `--json` / non-TTY exits 2 with
+`data.reason=missing_api_key`. Several saved keys and no selection exits 2 with
+`data.reason=profile_required`.
+
+Config lives in the `[openapi]` section of `~/.buildifyrc` (mode `600`). Do not pass `--api-key` on
+the command line, and do not commit the rc file or paste the secret into the repo.
+`BUILDIFY_OPENAPI_BASE_URL` and `BUILDIFY_OPENAPI_API_KEY` override the file at runtime.
+`BUILDIFY_OPENAPI_PROFILE` selects a saved profile. `BUILDIFY_OPENAPI_NO_PROMPT=1` disables the
+interactive prompt. `config set-key api_key` still updates the current profile, or the legacy single key.
+
+## Commands
+
+| Group | Commands |
+|-------|----------|
+| — | `health`, `version`, `help` |
+| `key` | `test` |
+| `bundle` | `list`, `nodes`, `node-properties`, `node-relations`, `doc`, `cred-types`, `cred-properties` |
+| `project` | `list`, `create`, `get`, `credentials`, `create-credential`, `workers` |
+| `workflow` | `list`, `create`, `get-draft`, `save-draft`, `validate`, `test-run`, `cancel-test`, `deploy`, `published`, `deployment` |
+| `config` | `init`, `set-key`, `add-profile`, `use`, `profiles`, `remove-profile`, `show` |
+
+Every command accepts `--json` for a single-line envelope
+(`{ok, code, msg, http_status, data}`) and maps failures onto stable exit codes:
+`0` ok, `1` generic, `2` auth/config, `3` local validation, `4` HTTP 4xx/5xx or validation errors,
+`5` network.
+
+## Example
+
+```bash
+buildify --json bundle nodes -b official/core
+buildify --json bundle node-properties -b official/core -n HttpRequestNode
+buildify --json workflow validate -p proj_xxx -f ./flow.json
+buildify --json workflow test-run -p proj_xxx -f ./flow.json --worker wk_xxx
+buildify --json workflow deploy -p proj_xxx -w wf_xxx --worker wk_xxx --wait
+```
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+python -m buildify_cli --help
+```
+
+`src/buildify_cli/usage.md` is the source of truth for `buildify help`; keep this README aligned
+for humans.