@limecloud/cli 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,293 @@
-# Temporary Holding Version
+# @limecloud/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lime Cloud 官方命令行客户端，提供 `limecloud-cli` 和 `limecloud` 两个命令。命令、参数、请求与响应来自本仓库的公共 OpenAPI，覆盖身份、开放平台、个人账户、运营和平台管理。要求 Node.js 22.12 或更高版本，使用 i18next 处理本地消息，采用 Apache-2.0 许可证。
+
+本仓库新增的安装引导以本轮后续发布的新版本为准；npm 的实际版本和内容以 registry 为准，构建和测试不会自动发布。
+
+本包参考官方 `@larksuite/cli@1.0.98` 的 npm 安装器与原生 REA 证据，提供安装引导、三层命令、Schema 自省、结构化输出、请求预览和设备授权，并按 Lime 的实际公共 API 组织领域。
+
+## 安装与首次使用
+
+手动安装：
+
+```sh
+npx @limecloud/cli@latest install
+```
+
+Agent 自动安装：将以下指令发送给你的 AI 工具。
+
+```text
+帮我安装 LimeCloud CLI：https://open.limeai.run/docs/zh-CN/cli-installation-guide.md
+```
+
+英文机器可读指南为 <https://open.limeai.run/docs/cli-installation-guide.md>。
+
+`install` 使用 npm 将本次运行的精确包版本安装到用户目录 `~/.local`，然后引导配置已登记的公共 CLI 客户端。缺少 Client ID 时，CLI 从当前身份服务的 `/runtime/v1/cli` 读取公开部署配置；响应必须与本次 Issuer 一致，不发送令牌或 Secret。部署未开放元数据或获取失败时，配置保持 `pending`，按提示向部署管理员获取公共 CLI Client ID 后手动配置。显式 Client ID 和已有配置优先，`--dry-run` 不读取网络元数据。
+
+安装完成后返回可执行文件目录与 PATH 提示；不会改写 shell 配置。用户明确选择后才发起设备授权，终端返回用户码、浏览器确认链接和恢复命令，不自动批准授权。
+
+```sh
+# 自定义安装目录，可用于隔离环境
+npx @limecloud/cli@latest install --prefix "/YOUR/INSTALL/PREFIX"
+
+# 仅查看安装与配置计划，不联网、不安装、不保存
+npx @limecloud/cli@latest install --dry-run
+
+# 自动化安装：显式配置，保留用户授权步骤
+npx @limecloud/cli@latest install \
+  --client-id "YOUR_REGISTERED_PUBLIC_CLI_CLIENT_ID" \
+  --issuer "https://YOUR_AUTH_ORIGIN" \
+  --api-origin "https://YOUR_API_ORIGIN" \
+  --skip-login
+```
+
+也可用 `LIMECLOUD_INSTALL_PREFIX` 设置安装目录。Windows 的默认目录同样位于当前用户的 `.local`，请通过 npx 执行安装，以复用 npm 的 JavaScript 入口。非交互运行不会询问或自动发起授权；缺少客户端时，结果明确标记配置为 `pending`，按返回命令完成后续步骤。`--no-config` 仅安装，`--login` 显式发起非阻塞设备授权，不能与 `--no-config` 或 `--skip-login` 同用。
+
+```sh
+limecloud-cli config init
+limecloud-cli auth login
+limecloud-cli auth status
+limecloud-cli doctor --offline
+limecloud-cli schema
+```
+
+安装失败会返回 `installation_failed`，检查 npm 网络和目标目录权限后重试同一命令。安装与配置不创建平台应用、不授予业务权限；CLI 不安装全局 Agent Skills。
+
+## 从仓库运行与分发
+
+```sh
+node "packages/cli/bin/limecloud-cli.mjs" --help
+node "packages/cli/bin/limecloud-cli.mjs" --version
+node "packages/cli/bin/limecloud-cli.mjs" schema
+node "packages/cli/bin/limecloud-cli.mjs" open --help
+node "packages/cli/bin/limecloud-cli.mjs" api list --format table
+```
+
+```sh
+pnpm --filter @limecloud/cli build
+pnpm --filter @limecloud/cli test
+npm pack "./packages/cli" --pack-destination ".dev/releases"
+```
+
+打包前需要存在 `.dev/releases/`。`prepack` 从 `contracts/openapi/identity.json` 和 `management.json` 生成随包合同、检查工作区版本，从 `contracts/i18n/locales.json` 复制唯一语言登记并检查对应 CLI 消息资源，再复制根 `LICENSE`。分发包仅包含命令入口、实现、公开合同、语言登记和消息、README 与许可证，不包含凭据、研究产物或测试夹具。npm 包的实际发布状态以 npmjs 为准；本仓库的构建与打包步骤不会自动发布。
+
+## 输出语言
+
+```sh
+limecloud-cli --help --locale zh-CN
+limecloud-cli schema open.application.list --locale zh-CN
+LIMECLOUD_LOCALE=en limecloud-cli api list
+```
+
+每次命令按 `--locale`、`LIMECLOUD_LOCALE`、`LC_ALL`、`LC_MESSAGES`、`LANG`、英文默认值的顺序协商。显式不支持的 `--locale` 会在读取凭据或请求网络前报错；环境语言未知时回退英文。POSIX 环境中的编码/修饰后缀会被移除，语言别名与明确前缀按统一登记归一，不会将繁体中文模糊匹配为简体中文。
+
+帮助、本地错误、设备授权通知和合同提供的摘要/描述按本次语言输出；合同缺少翻译时回退英文。请求发送规范 `Accept-Language`，响应语言由服务端协商。命令、选项、JSON/CSV 字段、错误码、Scope 与路径保持稳定，不用翻译消息判断程序结果。语言协商不修改配置或用户偏好，并发命令各自持有独立 i18next 实例。
+
+## 配置与登录
+
+先由平台明确登记公共 CLI 客户端，然后使用其 Client ID。交互式 `config init` 会询问身份服务、业务 API 来源和 Client ID；非交互运行可显式传参。CLI 不创建平台客户端、不保存客户端 Secret，也不会通过本地设置授予平台角色。
+
+```sh
+limecloud-cli config init \
+  --issuer "https://YOUR_AUTH_ORIGIN" \
+  --api-origin "https://YOUR_API_ORIGIN" \
+  --client-id "YOUR_REGISTERED_PUBLIC_CLI_CLIENT_ID"
+limecloud-cli config show
+limecloud-cli config set api_origin "https://YOUR_API_ORIGIN"
+```
+
+业务 API Origin 必须显式提供；CLI 不猜测尚未部署的正式地址。身份服务 Origin 和业务 API Origin 分别保存、分别校验；HTTP 仅允许本机回环地址。
+
+```sh
+limecloud-cli auth login
+limecloud-cli auth status
+limecloud-cli auth whoami
+limecloud-cli whoami
+limecloud-cli doctor --offline
+```
+
+默认登录仅请求 `openid profile email offline_access`。终端显示验证地址和用户码；用户在自己的浏览器核对客户端、权限及代码后决定是否授权。CLI 按服务端间隔轮询，收到 `slow_down` 后每次增加 5 秒，拒绝或到期即停止。浏览器同意不会被 CLI 自动批准。
+
+业务访问需显式请求对应 Scope，例如：
+
+```sh
+limecloud-cli auth login \
+  --scope "openid profile email offline_access lime:open:read"
+limecloud-cli auth check --scope "lime:open:read"
+limecloud-cli auth scopes
+```
+
+| Scope | 领域 |
+| --- | --- |
+| `lime:open:read` / `lime:open:write` | 工作空间、应用、配置、版本、客户端、分发、事件与协作者 |
+| `lime:account:read` / `lime:account:write` | 个人账户、空间、应用安装、报价、订单及账户安全 |
+| `lime:operations:read` / `lime:operations:write` | 商品、营销、订单、通知、财务及运营审计 |
+| `lime:admin:read` / `lime:admin:write` | 平台审核、访问绑定和管理审计 |
+
+Scope 控制委托入口，当前空间成员、领域角色、环境、修订号、幂等、强认证和独立审核仍由服务端检查。CLI 不会因调用失败自动扩大授权。`schema <service.resource.method>` 返回具体方法所需的 Scope。
+
+`auth scopes` 读取 OIDC 支持的 Scope，并报告本地授予记录；它不等于客户端已启用权限查询。`auth check --scope` 只核对当前未过期的本地授权。`auth status` 与根 `whoami` 显示本地有效上下文，不代替远端核验；`auth whoami` 调用真实 UserInfo。`doctor` 默认只检查本地配置、合同和令牌状态，不发网络请求。
+
+### 非阻塞设备授权
+
+```sh
+limecloud-cli auth login --no-wait --json
+limecloud-cli auth login --resume --json
+```
+
+`--no-wait` 输出 `verification_uri`、`user_code`、`expires_at` 和 `resume_command`，保密设备码只保存在私有 pending 文件。完成浏览器确认后用 `--resume` 继续；恢复保持原 Client ID、Issuer、API Origin、Scope 和安装上下文。为避免命令行历史泄露，Lime 使用本地恢复上下文，没有照搬裸传 `--device-code`。
+
+授权请求或令牌兑换结果未知时不重放旧设备码；需要重新发起登录。Ctrl+C 取消等待并释放锁，等待阶段可以随后恢复。强制终止进程可能遗留锁；CLI 不自动删除未知锁。
+
+## 三层命令
+
+优先选择对应任务的快捷命令，其次使用合同映射的领域命令，最后按已知公开路径调用。所有层次共享同一份合同校验和认证边界。
+
+```sh
+# 1. 快捷命令
+limecloud-cli identity +login
+limecloud-cli identity +whoami
+
+# 2. 领域命令
+limecloud-cli open application list --space-id "YOUR_SPACE_ID"
+limecloud-cli account profile get
+limecloud-cli operations product list --app-id "YOUR_APP_ID" --environment "sandbox"
+limecloud-cli admin review list --kind "releases"
+
+# 3. 按公开 HTTP 路径调用
+limecloud-cli api GET "/api/v1/open/spaces/YOUR_SPACE_ID/applications"
+limecloud-cli api GET "/api/v1/account/profile"
+```
+
+领域命令采用 `<service> <resource> <method>`，资源名使用 `snake_case`。当前合同包括 9 项 OAuth/OIDC 操作和 124 项委托管理操作；数量随 PRD、服务实现与公共合同更新。通过 `api list` 和 `schema` 查看当前版本，不以本说明中的数字替代运行时目录。
+
+```sh
+limecloud-cli schema open.application.create
+limecloud-cli schema open application create
+limecloud-cli schema open
+limecloud-cli api list application --format table
+```
+
+每个方法的 Schema 包含 `name`、`description`、`inputSchema`、`outputSchema` 和 `_meta`。路径、查询、HTTP Header、请求体、必填字段、字段 Flag、HTTP 方法、Scope、风险等级和文档入口均可发现。`--params` 支持路径及查询字段，`--header` 只允许合同声明的请求 Header；不能通过它覆盖 Authorization、Cookie 或 Host。
+
+```sh
+limecloud-cli open application get \
+  --params '{"spaceID":"YOUR_SPACE_ID","appID":"YOUR_APP_ID"}'
+```
+
+显式字段 Flag 覆盖同名 JSON 参数。管理客户端等命令中的 `--client-id` 是业务资源字段；需要覆盖当前 OAuth 客户端上下文时使用 `--auth-client-id`。登录和 `config init` 继续使用 `--client-id`。
+
+### JSON 与文件输入
+
+将以下内容保存为 `application.json`，包含创建应用所需的名称、描述、类型和预设图标：
+
+```json
+{
+  "name": "Example application",
+  "description": "An application for the example workflow",
+  "kind": "internal",
+  "icon": "leaf"
+}
+```
+
+```sh
+limecloud-cli open application create \
+  --space-id "YOUR_SPACE_ID" \
+  --data "@application.json" \
+  --dry-run
+```
+
+`--params JSON` 和 `--data JSON` 支持 `@file` 或 `-` 从 stdin 读取。OAuth/OIDC 方法按合同转换为表单编码；管理 API 保留 JSON 类型。密码、令牌和 Secret 等敏感字段需使用文件、stdin 或 `--param-env 字段=环境变量名`，不能作为普通命令行参数传入。
+
+```sh
+limecloud-cli identity token revoke \
+  --param-env "token=TOKEN_TO_REVOKE" \
+  --param "token_type_hint=refresh_token"
+```
+
+幂等方法可按 Schema 使用显式 Header：
+
+将当前环境与最新修订号保存为 `rotation.json`；示例中的 `1` 需替换为目标客户端的当前修订号：
+
+```json
+{ "environment": "sandbox", "revision": 1 }
+```
+
+```sh
+limecloud-cli open client rotate_secret \
+  --space-id "YOUR_SPACE_ID" \
+  --app-id "YOUR_APP_ID" \
+  --client-id "RESOURCE_CLIENT_ID" \
+  --header "Idempotency-Key=YOUR_UNIQUE_REQUEST_KEY" \
+  --data "@rotation.json" \
+  --dry-run
+```
+
+CLI 不自动生成或重试业务写请求的幂等键。结果未知时保留原键、原请求和上下文，按对应领域恢复流程处理。
+
+### 图标上传
+
+```sh
+limecloud-cli open application_icon create \
+  --space-id "YOUR_SPACE_ID" \
+  --file "cropped-icon.png" \
+  --dry-run
+```
+
+图标合同使用 `image/png` 原始二进制正文，不是 JSON 或 multipart。`--file -` 读取二进制 stdin。图标需预先裁剪为 256×256、最大 320KiB；服务端继续完整解码、重编码并检查当前权限。`--dry-run` 只展示文件尺寸、字节数和 SHA-256，不打印或发送图像字节。
+
+## 输出与请求预览
+
+默认成功输出到 stdout，退出码为 0：
+
+```json
+{ "ok": true, "identity": "user", "data": {}, "meta": {} }
+```
+
+失败输出到 stderr；参数校验失败退出码 2，其他失败通常为 1，SIGINT/SIGTERM 分别为 130/143：
+
+```json
+{ "ok": false, "error": { "type": "validation", "subtype": "invalid_argument", "code": "invalid_arguments", "message": "..." } }
+```
+
+错误可能包含上游稳定 `code`、HTTP `status` 及 `retry_after`，不回显服务端可能包含敏感输入的描述。判断命令是否成功使用退出码或 `ok`，不要把原始业务 API 的字段当作 CLI 成功标志。
+
+```sh
+limecloud-cli api list --format json
+limecloud-cli api list --format ndjson
+limecloud-cli api list --format table --fields "command,method,path"
+limecloud-cli api list --format csv --fields "command,method,path"
+```
+
+JSON 返回统一 Envelope；NDJSON 按记录逐行输出 Envelope；Table 与 CSV 输出所选数据字段。`--json` 等价于 `--format json`，`--fields` 支持逗号分隔的字段路径。Table 会去除终端控制字符。Lime 不依赖外部 jq，也不实现飞书专属身份切换或办公 API 分页假象。
+
+默认响应将访问令牌、刷新令牌、ID Token、设备码、客户端 Secret、密码和签名密钥等替换为 `[REDACTED]`。只有 API 调用显式 `--show-secrets` 才输出原始凭据；登录、状态与刷新始终不输出凭据。`--dry-run` 始终脱敏，即使同时指定 `--show-secrets`。
+
+`--dry-run` 只读取合同、配置与输入，验证后打印请求，不发 HTTP、不写入凭据、不触发业务操作。没有设置业务 API Origin 时，预览显示 `<api-origin>` 占位；实际调用会报配置缺失。
+
+## 凭据与环境隔离
+
+| 配置 | 用途 |
+| --- | --- |
+| `--issuer` / `LIMECLOUD_ISSUER` | 身份服务 Origin，默认 `https://auth.limeai.run` |
+| `--api-origin` / `LIMECLOUD_API_ORIGIN` | 显式业务 API Origin，无猜测默认值 |
+| `--client-id` / `--auth-client-id` / `LIMECLOUD_CLIENT_ID` | 已登记的 OAuth 公共客户端上下文 |
+| `LIMECLOUD_ACCESS_TOKEN` | 外部管理的用户访问令牌，不写入本地凭据 |
+| `LIMECLOUD_CLIENT_SECRET` | 仅适用于显式机密/机器客户端身份协议 API；公共 CLI 登录不使用 |
+| `LIMECLOUD_CONFIG` | 私有凭据文件，默认 `~/.config/limecloud/credentials.json` |
+| `LIMECLOUD_SETTINGS` | 公共设置文件，默认与凭据同目录的 `config.json` |
+| `LIMECLOUD_INSTALL_PREFIX` / `install --prefix` | CLI 安装前缀，默认当前用户的 `~/.local` |
+
+显式 Flag 优先于环境变量，之后使用设置文件和匹配的登录记录。每份凭据文件保存一个上下文；多环境可分别设置 `LIMECLOUD_CONFIG` 和 `LIMECLOUD_SETTINGS`。
+
+保存的令牌绑定 Issuer、Client ID 与 API Origin。改变 API Origin 不能把旧令牌发送到新站点，必须重新登录确认绑定。所有 HTTP 重定向都被拒绝，Authorization 不跟随重定向发送。`LIMECLOUD_ACCESS_TOKEN` 的来源与权限由调用者管理，服务端仍验证其 Scope、Audience 和当前领域权限。
+
+凭据、设置和 pending 文件使用当前用户所有的 0600 常规文件，拒绝符号链接及他人可读文件；认证写操作持有排他锁并原子替换。`auth refresh` 串行刷新，兑换前记录未知结果状态，成功后替换轮换令牌。网络失败或响应丢失后禁止重用旧刷新令牌，需重新登录。
+
+`auth logout` 先撤销保存的刷新令牌（若没有则撤销访问令牌），成功后清空本地记录；撤销失败保留信息以便恢复。`--local-only` 仅清空本地，不撤销远端，也不执行浏览器中央退出。设置了 `LIMECLOUD_ACCESS_TOKEN` 时，管理本地认证前需先清除该环境变量，CLI 不会误报外部令牌已被清除。
+
+## 验证边界
+
+本包测试覆盖公开合同完整目录与方法预览、真实 loopback Auth/API 分站 HTTP、表单与 JSON 编码、路径/查询/Header、设备授权及恢复、刷新结果未知防重放、格式化输出、二进制及 JSON stdin、PNG 上传入口、私有存储和凭据隔离。
+
+合同目录与请求预览不代替真实业务验收。正式业务 API、客户端登记和 PRD 场景须由本轮服务实现、数据库专项与部署验收证明；包发布不会自动部署平台。管理 BFF 的浏览器会话及 CSRF 入口保持独立，CLI 只调用公共合同中的路径。ID Token 不作为 CLI 凭据解析，应用需要验证 ID Token 时应使用完整 OIDC 库。

package/bin/limecloud-cli.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.mjs";
+// 下游命令提前关闭管道时安静结束，继续执行 finally 以释放私有文件锁。
+process.stdout.on("error", error => { if (error.code !== "EPIPE") throw error; });
+await run(process.argv.slice(2));