通过 pip 安装与使用 el CLI

使用 Python 3.11 或更新版本，安装 PyPI 包 envloop-cli 后即可运行 el，无需 clone 仓库、安装 EnvPlatform 或配置 GPU。本文按 2026-10-08 发布包 0.1.1 核对；源码 checkout 的功能可能与发布包不同。

安装

在已激活的 Python 3.11+ 虚拟环境中安装：

python3 --version
python3 -m venv "$HOME/.venvs/envloop-cli"
source "$HOME/.venvs/envloop-cli/bin/activate"
pip install envloop-cli
el --help
el train --help

也可使用已安装的 uv 将 CLI 安装为独立工具：

uv tool install --python 3.11 envloop-cli
# 若提示工具目录不在 PATH：运行 uv tool update-shell，再重开终端
el train --help

升级用 python -m pip install --upgrade envloop-cli；uv 用户用 uv tool upgrade envloop-cli。以下命令直接使用 el，不需要 uv run。

从 Dashboard 获取 KEY

登录已开通的 EnvLoop 账号，在 Dashboard → CONFIGURE → API Keys 创建目标工作区的平台机器 KEY。明文只显示一次。确认工作区 ID；KEY 和账号必须获授权访问该工作区。

将 KEY 保存在仓库外的私有纯文本文件中，只写一行 KEY，不写 export 或变量名。以下为 macOS / Linux 示例，只含占位符：

mkdir -p "$HOME/.config/envloop"
chmod 700 "$HOME/.config/envloop"
# 仅首次创建；已有文件时不要覆盖
(umask 077; printf '%s\n' 'YOUR_ENVLOOP_API_KEY' > "$HOME/.config/envloop/platform.key")
chmod 600 "$HOME/.config/envloop/platform.key"

通过可信编辑器或 secret manager 将文件中的占位符替换为 Dashboard KEY；不要把真实 KEY 粘贴到命令参数、shell 历史、日志或 Git。0600 表示只有文件所有者可读写。加载到当前终端：

export ENVLOOP_API_KEY="$(cat "$HOME/.config/envloop/platform.key")"

CLI 从环境变量读取 KEY，不自动读取此文件。重新打开终端后需重新加载。此 KEY 不是 Clerk sk_ / pk_、Cloudflare token 或 Tinker KEY。

连接平台与查询训练

--api-url 指向部署方提供的 API origin，生产通常为 https://api.envloop.ai，不要追加 /tinker 或 /v1/train。--workspace-id 使用 Dashboard 的工作区 ID。两者是全局参数，放在 train 之前；没有 --base-url 参数。

以下示例已完整指定连接参数。先从列表取得 train_job_id，再替换 TRAIN_JOB_ID：

el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train job list --limit 25
el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train job list --status running --limit 25
el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train job status TRAIN_JOB_ID
el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train billing usage 2026-10-08 2026-10-09
el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train checkpoint list --limit 25
el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train checkpoint list --session-id SESSION_ID --limit 25
el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train checkpoint list --run-id RUN_ID --limit 25

输出为 JSON。Train Job 的 train_job_id 与 Agent Job 的 job_id 分别使用；session/run ID 从训练详情或训练脚本记录取得，不用 Train Job ID 代替。任务列表返回 next_cursor 时，可用 train job list --cursor NEXT_CURSOR --limit 25 继续查询。checkpoint 只显示已登记的产物；空列表不表示训练已停止。当前 checkpoint 列表最多 100 条，没有 cursor 续页。

计费日期格式为 YYYY-MM-DD，位置参数依次为 starting_on 和 ending_before。当前平台只校验日期，实际用量尚未按日期区间过滤；estimate: true 是估算，不是该区间的正式账单或已结算金额。

也可配置默认连接，省略后续命令的全局参数：

export ENVLOOP_BASE_URL=https://api.envloop.ai
export ENVLOOP_WORKSPACE_ID=YOUR_WORKSPACE_ID
el train job list
el train job status TRAIN_JOB_ID
el train billing usage 2026-10-08 2026-10-09
el train checkpoint list

显式 --api-url / --workspace-id 覆盖相应环境变量。即使在同一工作区，另一用户的 KEY 也不会自动取得提交者的训练资源。

代理网络

CLI 尊重系统代理环境变量 HTTPS_PROXY、ALL_PROXY、NO_PROXY（也支持小写形式）。HTTPS 请求优先使用 HTTPS_PROXY；未设置协议代理时用 ALL_PROXY 回退。NO_PROXY 中的地址直连。

# 将端口替换为你的 HTTP 代理端口；HTTPS 目标可经 HTTP CONNECT 代理访问
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1
el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE_ID train job list

代理 URL 使用 HTTP 代理协议；当前传输不提供 SOCKS 支持。要让平台 API 直连，将 api.envloop.ai 加入 NO_PROXY。检查大小写变量是否冲突；不要将代理密码写入共享脚本或日志。

FAQ

Python 版本不满足，或系统拒绝 pip 安装？ 检查 python3 --version，使用 Python 3.11+ 创建上面的虚拟环境，或使用 uv tool install --python 3.11 envloop-cli。不需要用 sudo 改系统 Python。

el: command not found，或没有 train 子命令？ 激活安装包的虚拟环境；uv 用户检查工具 PATH。用 command -v el 确认没有命中旧 checkout 的入口，用 python -m pip show envloop-cli（uv 用户用 uv tool list）确认安装，再升级发布包。不要误装名称不同的 envloop 包。

NETWORK_ERROR、超时或证书错误？ 确认 API origin、DNS、网络和代理可用；核对 HTTPS_PROXY / ALL_PROXY / NO_PROXY。本地服务需要将回环地址列入 NO_PROXY。企业代理使用自定义 CA 时请按组织指引配置可信证书，不关闭 TLS 校验。

401 / 认证失败？ 确认当前终端加载了正确的平台机器 KEY，文件中没有占位符或变量名前缀，KEY 未过期、撤销。必要时在 Dashboard 创建新 KEY，安全更新文件后重新加载。不要打印 KEY 排查。

403 / 无权限？ 核对 KEY 所属用户、--workspace-id、有效工作区成员关系及角色；联系工作区管理员。其他用户的训练资源不因工作区相同而自动可见。

任务找不到、checkpoint 为空、或 503？ 确认训练 ID、资源所属用户和工作区，及 checkpoint 是否已保存并登记。503 请联系平台管理员检查训练服务；CLI 安装不等于 GPU 服务已部署。

配套版本与核对范围

安装与命令 help 已在隔离环境用 PyPI envloop-cli==0.1.1 核对，代理行为按该发布包的 HTTP 传输代码核对。平台计费限制按 EnvPlatform 3926e98 核对。未使用真实 KEY 调用生产训练、计费或 checkpoint API，未验证真实代理或 GPU 训练。

更多客户端命令见 CLI 参考；平台安装与权限说明见 EnvPlatform el CLI 指南。