标识
appaloft 是 Appaloft 的官方命令行工具。它是一等入口——所有命令都收集用户输入后通过共享业务操作执行，不会绕过应用层，也不维护另一套业务语义。
常用命令速查
appaloft init # 在当前目录初始化 appaloft.yml
appaloft up # 部署当前目录
appaloft login # 登录 Appaloft Cloud 或自托管实例
appaloft context list # 查看本机已保存的 profile/context
appaloft code # 占用默认 Server 上的我的 Sandbox
appaloft workspace # 管理 Workspace，并嵌入 Agent 原生 TUI
appaloft dev # 启动本地 Development TUI / foreground 会话
appaloft dev . --server <serverId> # 通过 live outbound Worker 远端开发
appaloft project list # 列出项目
appaloft server register --host <host> # 注册服务器
appaloft server worker enroll --server <id> --name <name> # 连接出站 Worker
appaloft resource create --project <id> # 创建资源
appaloft deployments timeline <deploymentId> # 查看部署时间线
appaloft resource diagnose <resourceId> # 生成安全诊断摘要
appaloft deployments recovery-readiness <deploymentId> # 查询恢复就绪状态每个命令都支持 --help 查看完整参数列表；交互式提示和错误恢复建议会尽量链接到本文档站点的稳定页面。
Up：第一次部署入口
appaloft up [path-or-source] [--yes] [--project <projectId>] [--json]appaloft up 是从文件夹到线上应用的主入口。省略路径时使用当前目录；Git 不是前置条件。
命令会复用现有文件夹 Project 关联，首次 Cloud 部署会在需要时折叠登录。编码 Agent、CI 和非
TTY 环境必须传入 --yes 才会执行登录写入、Project 创建或部署变更；--json 保持 stdout
为机器可读结果，进度仍在 stderr。命令只有在部署到达成功终态后才以 0 退出，失败终态非零
退出，也不会把预留或旧 URL 当成成功地址。
appaloft deploy 在 1.x 中仍是完全相同工作流的受支持兼容写法。新命令、文档和自动化应优先
使用 appaloft up。完整任务流程见第一次部署。
Workspace 快速入口
appaloft code 登录后占用团队默认已注册 Server 上的 我的 Sandbox。源是远端 SHA。
缺少 Adapter/Profile 时会创建不可见的 appaloft-remote。笔记本路径不是 Workspace
真相，脏树也不会上传。TTY 上默认 code 立刻进入占用 Workspace TUI，列表折叠，中间显示
preparing the agent 后再 attach。--no-attach 用一行 stderr 进度和占用横幅，不 attach。默认 code 会选 live 会话，
同名 leftover Profile 不能挡住第一次成功。--profile 只是兜底。--new 占用 cwd
源，不会静默 resume whoami。打开失败会写出正在打开的仓库以及缺少的 Binding 或
Profile。已注册 BYOS 就是放置目标，code 和 workspace open 的 --server 可钉死，不要求 managed。--local 才是本机
Scratch。
appaloft login
appaloft code
appaloft code --grok
appaloft code --pi
appaloft code --server <serverId>
appaloft code --no-attach
appaloft code --local
appaloft code --profile <installationId>
appaloft workspace open . --profile <workspace-profile> --new --server <serverId>appaloft workspace open [path|git-remote] 与 code 使用同一套定位参数，并走
workspaces.open。Git worktree 仍要求 clean 且已 push；非 git 目录通过 git remote
占用当前目录，不会复用无关会话。完整说明见
从本地目录打开 Agent。
appaloft workspace 在受支持的交互式 macOS/Linux 终端中打开 Workspace control TUI；它只消费
现有公开 operations/read models。Ctrl+] 从嵌入的 Agent 释放焦点，f 在同一 Session 上切换
Focus Mode，a 打开由状态决定的暂停、恢复与二次确认终止操作，并复用 headless CLI 的公开
命令。无 TTY、脚本或 Windows headless 场景使用 --no-tui、--json 或显式子命令；这些
路径不会加载 renderer。完整按键和会话边界见
管理正在运行的 Workspace。
Development Session 快速入口
appaloft dev [path] 使用部署配置生成公开 Development Plan，并在交互式 macOS/Linux 终端
打开原生 TUI。脚本使用 --no-tui、--detach 或 --json；plan/status/logs/stop/reset
提供相同生命周期的可重放入口。renderer 缺失会明确告警并安全进入 headless foreground。
appaloft dev plan .
appaloft dev . --env-file .env.development
appaloft dev status . --json
appaloft dev stop .
appaloft dev reset . --yes有 live outbound Server Worker 时添加 --server <serverId>，无需 inbound SSH。完整配置、状态、
HTTPS、watch 和 cleanup 说明见本地开发会话。
登录与 CLI Profile
appaloft login
appaloft login --url https://appaloft.internal.example.comappaloft login 和 appaloft auth login 默认连接 Appaloft Cloud（https://app.appaloft.com）。第一次 Cloud appaloft up 在没有 Profile 时会启动同一套浏览器登录，然后继续部署——不必先单独跑 appaloft login。appaloft deploy 在 1.x 中走同一兼容路径。要连接自托管 Appaloft 或其他受信任端点，需要显式传入 --url <url>。登录成功后，CLI 会把端点、Profile 名称、认证引用和握手摘要保存到本机 CLI Profile——这个 Profile 位于 APPALOFT_HOME 或用户本机 Appaloft home 目录，不属于仓库配置，不会被提交到 appaloft.yml。
登录不是部署接管，也不会创建 Project、Resource、Deployment、Source Link 或域名绑定,更不会把控制面配置塞进部署请求或把 Token/Cookie 写进已提交的配置文件。
appaloft auth status
appaloft logout
appaloft context list
appaloft context show
appaloft context use <profile>以上命令只管理本机 Profile/Context,不会修改任何服务端状态。
MCP 宿主安装
一条命令会给默认勾选的宿主同时写入 Skill 和 Local MCP。Token 留在 Appaloft CLI profile，不会写入编辑器配置：
appaloft login
appaloft setup agentappaloft setup agent 默认勾选 Universal、存在 ~/.claude 时的 Claude Code、存在 ~/.cursor 时的 Cursor；把相同 Skill 复制到 ~/.agents/skills、~/.claude/skills、~/.cursor/skills，再写入 token-free stdio 启动项到 ~/.claude.json 和 ~/.cursor/mcp.json。Universal 只写 Skill。OpenCode 在列表里但默认不勾选，需要 --agent opencode 或 appaloft auth mcp opencode install。显式 sibling 仍然可用：appaloft auth mcp cursor install、appaloft auth mcp claude-code install 和 appaloft auth mcp opencode install。npx skills add 仍然只复制 Skill。Codex 仍需要专用 bearer profile：appaloft auth mcp login 然后 appaloft auth mcp codex install。无 git 的目录可以用 appaloft up。
非交互认证(AI Agent / CI)
交互式登录使用浏览器验证码流程,适合人类操作者。当设置了 CLAUDECODE、CLAUDE_CODE_ENTRYPOINT、CURSOR_AGENT、AIDER_MODEL 或 CODEX_CLI，或进程是非 TTY / CI=1 时，appaloft up（以及 1.x 兼容写法 appaloft deploy）和 appaloft setup agent 会打印将要做的事，除非传入 --yes，否则不会创建项目、部署或写入 Skill。AI Agent 和 CI/自动化不应该使用浏览器/验证码流程作为默认认证路径,应该优先使用作用域受限、可过期的 Token:
# 一次性非交互命令
APPALOFT_TOKEN=<scoped-token> appaloft up --yes
# 从标准输入读取 Token,验证后写入本机 Profile
appaloft auth token login --stdin
# 从受控密钥文件读取(Agent 不应打开或打印该文件内容)
appaloft auth token login --token-file <path>不要把明文 Token 作为命令行参数传入,也不要把 Session Cookie、Bearer Token、Deploy Token 或密钥文件内容粘贴到对话、日志、截图或已提交的配置文件中。
远程 Appaloft 调度
有已登录的 Profile,或显式传入 --control-plane-mode cloud|self-hosted、--control-plane-url <url> 时,普通业务命令会先解析执行目标:
appaloft up --control-plane-mode self-hosted --control-plane-url https://console.example.comcontrolPlane.mode: none(默认)继续使用本地 CLI/SSH 运行时。远程目标会在业务请求前执行兼容性/认证握手,再通过和 Web/API/SDK 完全相同的类型化契约调度操作——CLI 不维护另一份业务 Schema。
没有 Profile、URL、Token 或其他受信任远程来源时,auto 和默认行为会回落到本地模式,不会联系公共 Cloud,也不会扫描网络。
server terminal、resource terminal 在远程目标下会先通过类型化 API 打开 Session;加 --attach 后 CLI 直接连接控制面 WebSocket 转发本地终端的输入、resize、输出和关闭帧,不会初始化本地状态,也不会读取目标服务器的 SSH 凭据。
部分命令(serve、db、remote-state、init、Source Package 等)目前仍只支持本地执行;在显式远程模式下调用会返回 control_plane_unsupported,不会静默改走本地执行。顶层 up / deploy 会按已选 Profile 调度受支持的远端控制面。
本地文档链接
当 Appaloft 本地服务正在运行时,CLI 打印的文档链接会优先指向本地 /docs/*,方便离线自托管用户无需访问外部站点。
自动化建议
编写自动化脚本时,优先使用明确的 flag 或配置文件字段,避免依赖无法重放的交互式输入(例如确认提示)。