CLI reference

命令结构

CLI 是一等入口。命令应该收集用户输入，然后通过共享业务操作执行，而不是绕过应用层。

帮助链接

CLI --help、交互式 prompt 和错误恢复提示应该链接到稳定 public docs anchor。当前 help registry 尚未实现，本页先定义目标位置。

远程控制面登录

appaloft login --url <url> 和 appaloft auth login --url <url> 会把 Appaloft Cloud 或自托管控制面的 endpoint、profile 名称、认证引用和握手摘要保存到本机 CLI profile。这个 profile 位于 APPALOFT_HOME 或用户本机 Appaloft home，不属于仓库配置。

登录需要先通过 /api/version 兼容性发现和当前组织上下文校验。appaloft auth status、appaloft logout、appaloft auth logout、appaloft context list、appaloft context show、appaloft context use <profile> 只管理本机 profile/context。

登录不是部署接管，也不是 SSH PGlite state adoption。它不会创建 project、resource、deployment、source link、domain binding，不会把 controlPlane 塞进 deployments.create，也不会把 token、cookie、database URL、SSH key、credential id、tenant/org secret identity 写进 committed appaloft.yml。

当前 Cloud 支持需要显式 --url 和受信任的本机 token 或 session 输入；默认 Cloud URL、浏览器/device/OIDC 登录仍属于后续能力。

远程控制面 dispatch

有 active profile，或显式传入 --control-plane-mode cloud|self-hosted、--control-plane-url <url>、APPALOFT_CONTROL_PLANE_MODE、APPALOFT_CONTROL_PLANE_URL 时，普通 CLI 业务命令会先解析执行目标。controlPlane.mode: none 和 --control-plane-mode none 继续使用本地 CLI/SSH runtime。

远程目标会在业务请求前执行兼容性/auth handshake，然后通过同一套 typed HTTP/API contract dispatch 非 streaming、非 webhook-signature 的 generated SDK operation。CLI 不维护另一份业务 schema；同一个 operation key 和 input schema 也服务于 HTTP/oRPC、Web、SDK 和 future MCP。

没有 profile、URL、token 或其他受信任远程来源时，auto 和默认行为会回落到本地模式。这个回落不会联系 public Cloud、不会扫描网络、不会上传或 adopt SSH PGlite state。

serve、db、remote-state、init、top-level quick deploy、本地 terminal attach/source-package/streaming 类命令仍保持本地或在显式 remote mode 下报 control_plane_unsupported。远程已选择但 auth、handshake 或 operation capability 不满足时，CLI 会失败，不会静默改走本地执行。

本地文档路径

当 Appaloft 本地服务运行时，CLI 文档链接应优先指向本地 /docs/*，避免离线自托管用户必须访问外部站点。

自动化使用

自动化脚本应优先使用明确 flag 或配置文件字段，避免依赖无法重放的交互输入。