runpod-companion-clis

用途

该技能汇集 Runpod 工作流中常用的四个第三方命令行工具，为每款工具提供在 Runpod 场景下的凭据配置与命令参考。当任务只涉及其中某一个操作时，只需加载对应的那一份参考文档，而非全部四份。

若任务是从头创建或改进一个有文档的模板项目，应先使用 runpod-build-template，再回到本技能执行具体 CLI 操作。若输入是模型文件名缺少已验证 URL 或哈希的 ComfyUI 工作流，应转向 runpod-templates 中的 ComfyUI 模型修复指南；只有当确切的 Hugging Face 仓库/文件已知、任务仅是下载、缓存或打包该产物时，才回到本技能。

四个 CLI 及主要能力

CLI	用途	完整参考
hf（HuggingFace）	从 Hub 下载模型，以便缓存或打包进镜像	reference/huggingface.md
gh（GitHub）	管理 worker 仓库并创建 release（Hub 索引的是 release）	reference/github.md
docker	构建、校验并推送镜像到 Docker Hub，供 Runpod 拉取	reference/docker.md
aws（S3）	通过 Runpod 的 S3 API 读写网络卷存储	reference/aws.md

每个工具使用前都需要凭据。各工具的认证步骤与命令见对应参考文档；安装步骤单独放在一次性的 <cli>-setup.md 中，仅在 CLI 尚未安装时才需要打开。

这些 CLI 通常只是更大任务中的一个步骤。完整任务的已验证示例见 runpod/golden-paths/README.md，例如模型的打包与挂载（25）、构建最小镜像（22）、把数据迁移到网络卷（07）。

由于这些是第三方 CLI，各自有独立的发布节奏，因此 <cli> --help 才是参数和子命令的权威来源；本技能的参考文档覆盖 Runpod 相关用法和常见陷阱，而非工具的全部能力。在断言某个工具做不到某事之前，请先查看 --help。

使用方式（各 CLI 要点）

Windows 环境

先选定 shell，必要时再配置 WSL2。安装新副本前先检查已有的原生、WSL2 或远程工具。本技能中 Windows 下的 hf 与 gh 配置方案使用 WSL2 及其 Linux 安装器。若选择该路线且缺少 WSL2，请以管理员身份在 PowerShell 中运行 wsl --install，如有提示则重启；随后打开 Ubuntu 应用完成设置，再按各参考文档中的 Linux 说明操作。命令、凭据和路径应保留在所选环境中。仅进行文件编写不需要安装这些 CLI。

HuggingFace CLI

将模型下载到本地，以便在 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

管理 worker 仓库并创建 release。认证与命令见 reference/github.md（安装与 SSH 密钥设置见 reference/github-setup.md）。

• Hub 索引的是 release 而非 commit，每次更新 Hub 列表都需要新的 gh release create。
• 一把 SSH 密钥（ssh-keygen -t ed25519）可同时注册到 GitHub（gh ssh-key add）和 HuggingFace（在浏览器中粘贴）。

Docker

构建、校验并推送镜像到 Docker Hub。凭据与命令见 reference/docker.md（安装见 reference/docker-setup.md）。

• 始终以 --platform=linux/amd64 构建——Runpod 运行在 x86 Linux 上。
• 始终使用明确的语义化标签，绝不使用 latest——latest 并不追踪最新推送，worker 可能静默拉取到错误镜像。
• Docker Hub 认证使用个人访问令牌而非密码。私有镜像需在 Console → Container Registry Settings 中登记一次凭据。

AWS CLI

通过 Runpod 的 S3 兼容 API 访问网络卷存储（存储桶名称 = 网络卷 ID）。凭据、区域规则与命令见 reference/aws.md（安装见 reference/aws-setup.md）。

• 这是 Runpod 的 S3 API，不是 AWS：access key = Runpod 用户 ID（user_...），secret = S3 API key（rps_...）。
• S3 API 密钥只能在 Console 中生成，runpodctl/REST/GraphQL 均无法创建。若 ~/.aws/credentials 或环境变量中尚无密钥且需要 S3 访问，应停止并请用户在 Settings > S3 API Keys 中生成。
• 每条命令都需要 --region DATACENTER --endpoint-url https://s3api-DATACENTER.runpod.io/（datacenter 指卷所在的数据中心，而非 AWS 区域）。
• 大文件/多文件传输需要可靠续传时，参见 reference/aws.md 的可选可续传网络卷传输部分。

适用场景

• 在构建镜像前把 HuggingFace 模型缓存到本地。
• 更新 worker 仓库并创建 release，使 Hub 列表同步更新。
• 为 Runpod 构建、校验并推送 linux/amd64 镜像。
• 通过 S3 API 向 Runpod 网络卷上传或读取数据。

限制

• 四个 CLI 均为第三方工具，各自独立发布，本技能只覆盖 Runpod 相关用法与陷阱，完整参数需查阅 --help。
• 使用前必须配置各自凭据；S3 API 密钥无法通过 runpodctl/REST/GraphQL 生成。
• 部分安装与配置步骤（如 Windows 下 WSL2 路线）依赖所选环境，具体安装命令未在技能正文中完整给出，需参见对应 setup 文档。
• 涉及具体价格、账号权限或平台行为的信息，资料中暂未提供。