命令行

想在终端或脚本里批量进出数据，命令行是最快的方式。它和控制台调用的是同一套公开 REST API，安装后有两个等价的命令名：embodiflow 和更短的 ef。

只要标准输出不是终端，命令就输出 JSON，脚本和智能体可以直接解析。加 --json 可以强制输出 JSON，加 --output table 则输出便于阅读的表格。所有命令都支持 --api-base-url <url> 和 --profile <name>。

安装

包名是 @embodiflow/cli，发布在组织的 GitHub Packages 仓库，安装前需要有该仓库的读取权限。

npm install --global @embodiflow/cli --registry=https://npm.pkg.github.com
embodiflow --help

登录

auth login 会打开浏览器让你在那里登录。在自动化场景里，可以改用个人访问令牌：--pat 用于粘贴令牌，--pat-stdin 从标准输入读取。默认连接生产 API（https://api.embodiflow.io），用 --base-url 可以换成其他地址。

embodiflow auth login --base-url https://api.embodiflow.io
embodiflow whoami --json

whoami 显示你当前的登录身份：邮箱、当前团队、令牌类型、权限范围和过期时间。embodiflow auth logout 删除已保存的凭据，embodiflow config doctor 检查命令行能否连上它需要的所有服务。

主要命令

项目

embodiflow projects list --json

embodiflow projects create --name "Pick and place"

上传

embodiflow uploads create --project-id <project-id> --source-path ./recordings

uploads create 需要项目 UUID（--project-id）和一个文件夹，其中每个录制文件夹都会成为一条录制。想先看看会发生什么？uploads plan 使用相同的 --source-path，只输出一份只读计划，不会创建任何东西。

要用自己起的名字上传单条录制，请使用 recordings upload <path>。项目用 --project <team>/<project>（或项目 UUID）指定，--name 设置录制名称。

embodiflow recordings upload ./recordings/rec-0001 --project <team>/<project> --name rec-0001

工作流运行

embodiflow workflow runs list --project-id <project-id>

embodiflow workflow runs wait <run-id>

workflow runs wait 会一直轮询到运行结束，很适合放在上传脚本的最后。

导出与下载

embodiflow exports create --project-id <project-id> --version-number 1

embodiflow versions download <team>/<project>@1 --format lerobot-v3

exports status、exports wait 和 exports download 需要 --project-id、--version-number 和 --export-id。如果手上只有 team/project@n 这样的引用，resolve <ref> 可以查出背后的 ID。

训练

embodiflow training jobs list --project-id <project-id>

embodiflow training checkpoints download --job <job-id> -o weights.tar

training checkpoints download 把任务的最后一个检查点下载到本地，并校验大小和校验和。用 --checkpoint 可以指定其他检查点。

Webhook

embodiflow webhook-endpoints create --url https://example.com/hooks --event-types workflow.run.succeeded

签名密钥只显示一次，请马上保存。如何校验每次投递，见签名校验。

查看更多

embodiflow schema commands --json
embodiflow <command> --help

schema commands 输出完整的、机器可读的命令和参数列表。本页就是根据它写的，有出入时以它为准。

退出码

脚本可以依赖下面这些约定。命令失败时，退出码一定不为 0。

• 0 成功。
• 1 命令失败：API 错误、校验失败、找不到对象，或者还没有登录。
• 2 用法错误：未知命令或缺少参数。
• 3 uploads create 已经存好所有文件，但处理没有开始。按输出的原因排除问题后，运行 uploads create --resume 重新提交，不用重新上传。