companion-clis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Companion CLIs

配套CLI工具

Four CLIs commonly needed alongside Runpod. Each has its own credentials + command reference in

reference/

— plus a one-time

<cli>-setup.md

for install (only opened if the CLI isn't installed). Load only the one the task needs, not all four.

CLI	Use it to	Full reference
`hf` (HuggingFace)	Download models from the Hub to cache/bake into images	reference/huggingface.md
`gh` (GitHub)	Manage worker repos + cut releases (Hub indexes releases)	reference/github.md
`docker`	Build/validate/push images to Docker Hub for Runpod to pull	reference/docker.md
`aws` (S3)	Read/write network-volume storage over Runpod's S3 API	reference/aws.md

Each requires credentials before use. Read the per-tool reference for auth steps and commands; install is a separate one-time

<cli>-setup.md

Runpod 常用的四款配套 CLI 工具。每款工具在

reference/

目录下都有独立的凭证说明 + 命令参考文档，还有一份仅需执行一次的

<cli>-setup.md

安装指南（仅在未安装该 CLI 时查看即可）。只需加载任务所需的那一款工具，无需全部加载。

CLI 工具	用途	完整参考文档
`hf` （HuggingFace）	从 Hub 下载模型并缓存/打包到镜像中	reference/huggingface.md
`gh` （GitHub）	管理工作节点仓库并创建版本发布（Hub 会索引版本发布内容）	reference/github.md
`docker`	构建、验证并推送镜像至 Docker Hub，供 Runpod 拉取使用	reference/docker.md
`aws` （S3）	通过 Runpod 的 S3 API 读写网络卷存储	reference/aws.md

每款工具使用前都需要配置凭证。请查看对应工具的参考文档了解认证步骤和命令；安装操作请参考独立的一次性指南

<cli>-setup.md

。

Windows: Install WSL2 First

Windows 用户：先安装 WSL2

If you are on Windows, install WSL2 before proceeding — it gives you the native Linux environment all these CLIs target. In PowerShell as Administrator, then restart:

powershell

wsl --install

Afterward open the Ubuntu app to finish setup, then follow the Linux instructions in each reference.

如果你使用 Windows 系统，请先安装 WSL2 再进行后续操作——这些 CLI 工具均针对原生 Linux 环境开发，WSL2 可提供该环境。以管理员身份打开 PowerShell，执行以下命令后重启电脑：

powershell

wsl --install

之后打开 Ubuntu 应用完成初始化设置，然后遵循各参考文档中的Linux操作说明即可。

HuggingFace CLI

Download models locally so they're cached for a Docker build/run. Auth and

hf download

recipes: reference/huggingface.md (install: reference/huggingface-setup.md).

Use the standalone
```
hf
```
CLI, not
```
pip install huggingface_hub
```
(that's the older
```
huggingface-cli
```
with different syntax).
Auth via
```
hf auth login
```
, or
```
export HF_TOKEN=hf_...
```
(env var wins over saved token).

将模型下载到本地缓存，以便用于 Docker 构建/运行。认证方法和

hf download

使用示例请查看：reference/huggingface.md（安装指南：reference/huggingface-setup.md）。

使用独立的
```
hf
```
CLI，不要使用
```
pip install huggingface_hub
```
（这是旧版的
```
huggingface-cli
```
，语法不同）。
通过
```
hf auth login
```
进行认证，或设置环境变量
```
export HF_TOKEN=hf_...
```
（环境变量优先级高于已保存的令牌）。

GitHub CLI

Manage worker repositories and cut releases. Auth and commands: reference/github.md (install + SSH-key setup: reference/github-setup.md).

The Hub indexes releases, not commits — every Hub listing update needs a new
```
gh release create
```
.
One SSH key (
```
ssh-keygen -t ed25519
```
) registers with both GitHub (
```
gh ssh-key add
```
) and HuggingFace (paste in browser).

管理工作节点仓库并创建版本发布。认证方法和命令请查看：reference/github.md（安装 + SSH 密钥配置：reference/github-setup.md）。

Hub 仅索引版本发布内容，而非提交记录——每次更新 Hub 列表都需要执行新的
```
gh release create
```
命令。
生成一对 SSH 密钥（
```
ssh-keygen -t ed25519
```
），即可同时注册到 GitHub（执行
```
gh ssh-key add
```
）和 HuggingFace（在浏览器中粘贴密钥）。

Docker

Build, validate, and push images to Docker Hub. Credentials and commands: reference/docker.md (install: reference/docker-setup.md).

Always build
--platform=linux/amd64
— Runpod runs on x86 Linux.
Always use explicit semantic tags; never
latest
—
```
latest
```
doesn't track the newest push, so workers can silently pull the wrong image.
Docker Hub auth uses a personal access token, not your password. For private images, register the credential once in Console → Container Registry Settings.

构建、验证并推送镜像至 Docker Hub。凭证配置和命令请查看：reference/docker.md（安装指南：reference/docker-setup.md）。

构建时务必指定
--platform=linux/amd64
——Runpod 运行在 x86 架构的 Linux 系统上。
始终使用明确的语义化标签；切勿使用
latest
——
```
latest
```
不会跟踪最新推送的镜像，可能导致工作节点静默拉取错误的镜像。
Docker Hub 认证需使用个人访问令牌，而非你的密码。若使用私有镜像，请在控制台 → 容器注册表设置中一次性注册凭证。

AWS CLI

Access network-volume storage over Runpod's S3-compatible API (bucket name = network volume ID). Credentials, region rules, and commands: reference/aws.md (install: reference/aws-setup.md).

Runpod's S3 API, not AWS: access key = Runpod user id (
```
user_...
```
), secret = S3 API key (
```
rps_...
```
).
S3 API keys are Console-only. No
```
runpodctl
```
/REST/GraphQL creates them — if they're not already in
```
~/.aws/credentials
```
/env and S3 access is needed, stop and ask the user to generate them (Settings > S3 API Keys).

Every command needs

--region DATACENTER --endpoint-url https://s3api-DATACENTER.runpod.io/

(datacenter = the volume's DC, not an AWS region).

For large/many-file transfers with reliable resume, see reference/aws.md → optional resumable volume transfers.

通过 Runpod 兼容 S3 的 API 访问网络卷存储（存储桶名称 = 网络卷 ID）。凭证配置、区域规则和命令请查看：reference/aws.md（安装指南：reference/aws-setup.md）。

这是 Runpod 的 S3 API，并非 AWS 官方 API：访问密钥 = Runpod 用户 ID（
```
user_...
```
），密钥密码 = S3 API 密钥（
```
rps_...
```
）。
S3 API 密钥仅能在控制台生成。无法通过
```
runpodctl
```
/REST/GraphQL 创建密钥——如果
```
~/.aws/credentials
```
文件或环境变量中没有配置密钥，但又需要访问 S3，请暂停操作并请求用户生成密钥（路径：设置 > S3 API 密钥）。
每条命令都需指定
```
--region DATACENTER --endpoint-url https://s3api-DATACENTER.runpod.io/
```
（其中 DATACENTER 是网络卷所在的数据中心，而非 AWS 区域）。
如需可靠断点续传大文件或大量文件，请查看 reference/aws.md → 可选的可续传卷传输工具。