companion-clis

어떤 스킬인가요?

Companion CLIs for Runpod workflows — HuggingFace, GitHub, Docker, and AWS. Use the ComfyUI model-repair guide in runpod-templates instead when an imported ComfyUI workflow lacks model download metadata.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# AWS CLI — one-time setup

Install the AWS CLI (only needed once, if `aws --version` fails). Credentials, region
rules, and commands are in [`aws.md`](aws.md).

```bash
# macOS
brew install awscli

# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip && sudo ./aws/install
```

# AWS CLI

The AWS CLI is used to access Runpod storage over the S3 protocol. Any Runpod product that can mount a Network Volume — pods, clusters, and serverless endpoints — can have its storage accessed this way. The bucket name is the network volume ID.

> **Not installed?** One-time install lives in [`aws-setup.md`](aws-setup.md) — skip if `aws --version` already works.

## Credentials

Runpod uses its own S3-compatible API, not AWS. You need a Runpod user ID and S3 API key — not an AWS account.

- **Access key** (`AWS_ACCESS_KEY_ID`): your Runpod user ID — found in the console under Settings > S3 API Keys, in the key description (format: `user_...`)
- **Secret key** (`AWS_SECRET_ACCESS_KEY`): an S3 API key — generate one at Settings > S3 API Keys > Create. Shown only once; save it immediately (format: `rps_...`)

> **S3 API keys are Console-only.** There is **no** `runpodctl` command and **no**
> REST/GraphQL endpoint to create an S3 API key or read the user ID; both come from the
> Console (Settings > S3 API Keys), so an agent cannot self-provision them. (This differs
> from the regular `RUNPOD_API_KEY`, which the CLI can save.) Note the AWS access key must
> be the Runpod **user id** (`user_...`), not the `RUNPOD_API_KEY`.
>
> **Rule:** if an operation needs S3-API access and no S3 credentials are present in
> `~/.aws/credentials` or env vars, stop and ask the user to generate them in the Console —
> do not attempt to self-provision them.

```bash
# Option 1: interactive configure (writes ~/.aws/credentials and ~/.aws/config)
# When prompted: enter user ID as access key, S3 API key as secret.
# Press Enter to skip region and output format — region is always passed per-command, not stored in config.
aws configure

aws configure list    # verify stored credentials

# Option 2: environment variables (override config files)
export AWS_ACCESS_KEY_ID=user_...
export AWS_SECRET_ACCESS_KEY=rps_...

# To stop using env vars and fall back to config file:
unset AWS_ACCESS_KEY_ID
unset AWS_SECRET_ACCESS_KEY
```

## Region and Endpoint

The `--region` flag on every command is the Runpod datacenter ID where the network volume lives — not an AWS region. The `--endpoint-url` is derived from the same datacenter ID.

Every command requires both flags. **`--region` takes the DC id as-is, but the
`--endpoint-url` host must be LOWERCASED** — `s3api-eu-ro-1…`, not `s3api-EU-RO-1…`
(an upper-cased host fails to resolve):
```
--region <DC> --endpoint-url https://s3api-<dc-lowercased>.runpod.io/
# DC EU-RO-1  →  --region EU-RO-1  --endpoint-url https://s3api-eu-ro-1.runpod.io/
```

**Tip:** Each network volume on the storage page at https://console.runpod.io/user/storage/ shows a pre-filled example `aws s3 ls` command with the correct `--region` and `--endpoint-url` already substituted. Use this to confirm the exact values for a given volume.

Datacenter IDs are **region-prefixed**; they go verbatim into `--region <DC>` but must be
**lowercased** in the host `https://s3api-<dc-lowercased>.runpod.io/`. `runpodctl datacenter
list` is authoritative — the set grows over time; run it for the current list. Common ones:

| Region | Datacenter IDs |
|--------|---------------|
| EU | EU-CZ-1, EU-RO-1, EU-NL-1, EU-FR-1, EUR-IS-1, EUR-NO-1 |
| US | US-CA-2, US-GA-1, US-GA-2, US-IL-1, US-KS-2, US-MD-1, US-MO-1, US-NC-1, US-TX-1, US-WA-1 |
| Other | CA-MTL-1, AP-JP-1, AP-IN-1, SEA-SG-1, OC-AU-1 |

## Key Commands

Replace `DATACENTER` (in `--region`) with your network volume's datacenter ID **as-is**
(e.g. `US-CA-2`), `<dc-lowercased>` (in the host) with that **same id lowercased**
(`us-ca-2`), and `NETWORK_VOLUME_ID` with the volume ID (the S3 bucket name).

```bash
# List files in a volume
aws s3 ls \
  --region DATACENTER \
  --endpoint-url https://s3api-<dc-lowercased>.runpod.io/ \
  s3://NETWORK_VOLUME_ID/

# List a subdirectory
aws s3 ls \
  --region DATACENTER \
  --endpoint-url https://s3api-<dc-lowercased>.runpod.io/ \
  s3://NETWORK_VOLUME_ID/my-folder/

# Upload a file
aws s3 cp local-file.txt \
  --region DATACENTER \
  --endpoint-url https://s3api-<dc-lowercased>.runpod.io/ \
  s3://NETWORK_VOLUME_ID/

# Download a file
aws s3 cp \
  --region DATACENTER \
  --endpoint-url https://s3api-<dc-lowercased>.runpod.io/ \
  s3://NETWORK_VOLUME_ID/remote-file.txt ./

# Delete a file
aws s3 rm \
  --region DATACENTER \
  --endpoint-url https://s3api-<dc-lowercased>.runpod.io/ \
  s3://NETWORK_VOLUME_ID/remote-file.txt

# Sync a local directory to a volume
aws s3 sync local-dir/ \
  --region DATACENTER \
  --endpoint-url https://s3api-<dc-lowercased>.runpod.io/ \
  s3://NETWORK_VOLUME_ID/remote-dir/
```

Path mapping: `/workspace/my-folder/file.txt` on a pod = `s3://NETWORK_VOLUME_ID/my-folder/file.txt` via S3.

## Troubleshooting

```bash
# Retry on timeout (large transfers)
export AWS_RETRY_MODE=standard
export AWS_MAX_ATTEMPTS=10

# Extend read timeout for large files (seconds)
aws s3 cp large-file.zip \
  --region DATACENTER \
  --endpoint-url https://s3api-<dc-lowercased>.runpod.io/ \
  --cli-read-timeout 7200 \
  s3://NETWORK_VOLUME_ID/
```

## Optional: resumable volume transfers (community tool)

`aws s3 sync` is fine for modest trees but has weak resume and struggles past ~10,000
files — painful for large model weights or when replicating the same data to several
volumes (see golden path [10 — multi-region HA serverless](../../runpod/golden-paths/10-multi-region-ha-serverless.md)).
For that, the community **Runpod Network Volume Storage Tool** wraps the same S3 API
with **resumable multipart uploads** (auto chunk sizing, MD5-verified resume),
directory sync with excludes, an interactive file browser, a Python SDK, and a REST
server. It's referenced in the official docs under
[community solutions](https://docs.runpod.io/community-solutions/runpod-network-volume-storage-tool).

```bash
git clone https://github.com/justinwlin/Runpod-Network-Volume-Storage-Tool.git
cd Runpod-Network-Volume-Storage-Tool && uv sync

# Same S3 credentials as the AWS CLI above (access key = user id, secret = rps_... key)
export RUNPOD_API_KEY=...
export RUNPOD_S3_ACCESS_KEY=user_...
export RUNPOD_S3_SECRET_KEY=rps_...

uv run runpod-storage upload ./model-artifacts <volume-id>   # resumable — re-run to resume
uv run runpod-storage list-volumes
```

Plain `aws s3` (above) stays the zero-dependency baseline; reach for this tool when
resume/large-tree reliability matters.

# Docker — one-time setup

Install Docker (only needed once, if `docker --version` fails). Credentials, tagging,
and build/push commands are in [`docker.md`](docker.md).

**macOS:** Download Docker Desktop from https://docs.docker.com/desktop/setup/install/mac-install/
- Choose the **Apple Silicon** installer for M-series Macs, or **Intel Chip** for older Macs
- Open the DMG, drag Docker to Applications, and launch it

**Windows:** Download Docker Desktop from https://docs.docker.com/desktop/setup/install/windows-install/
- Requires WSL 2 — install it first if needed (`wsl --install` in an admin PowerShell, then restart); Docker Desktop then detects it automatically
- After installation, `docker` commands work inside your WSL2 terminal without extra configuration
- Run the installer and follow the setup wizard

**Linux:** See https://docs.docker.com/engine/install/ for distro-specific instructions

```bash
# Linux convenience script (Ubuntu/Debian)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER   # allow non-root usage (re-login after)
```

# Docker

Docker is used to build and validate container images locally before pushing to Docker Hub. Runpod uses Docker Hub as its default image registry — serverless endpoints, pods, and templates all reference images by their Docker Hub tag. Once an image is pushed, Runpod workers pull it automatically when the endpoint or pod is started.

> **Not installed?** One-time install lives in [`docker-setup.md`](docker-setup.md) — skip if `docker --version` already works.

## Credentials

Docker Hub authentication uses a personal access token (PAT), not your account password.

1. Go to https://app.docker.com → Avatar (top right) → Account Settings → Personal Access Tokens
2. Click **Generate new token** — give it a descriptive name, set an expiration, and choose **Read & Write** access
3. Copy the token immediately — it is shown only once

```bash
docker login -u DOCKERHUB_USERNAME
# When prompted for a password, paste your personal access token
```

Credentials are saved to `~/.docker/config.json` after a successful login.

## Tagging

> **Always use explicit semantic version tags. Never rely on `latest`.**
> Full rationale (why `latest` is mutable/unreliable, digest pinning, and the x86
> `--platform` rule) lives in the canonical
> [runpod-usage Docker reference](../../runpod-usage/reference/docker.md) — don't restate it here.

Use a tag that uniquely identifies the build: `v1.0.0`, `v1.0.1`, etc.

```bash
# Correct: explicit semantic version tag
docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 .
docker push myorg/myimage:v1.0.0

# Wrong: latest tag is ambiguous and unreliable
docker build -t myorg/myimage:latest .
```

## Docker Hub

Docker Hub is the registry Runpod pulls images from. After pushing, images are visible at https://hub.docker.com/repositories/ and referenceable in Runpod as `username/image:tag`.

Images on Docker Hub can be public (anyone can pull) or private (requires credentials). For private images, register your Docker Hub credentials in Runpod once and they become available to any template:

1. Go to https://console.runpod.io/user/settings → **Container Registry Settings**
2. Add your Docker Hub username and personal access token (the same PAT used for `docker login`)
3. When creating or editing a template, select the saved credential from the dropdown

> Runpod currently only supports `docker login` type credentials for container registry authentication.

## Key Commands

```bash
# Build for Runpod (always --platform=linux/amd64 — pods run on x86 Linux)
docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 .
docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 -f Dockerfile.prod .  # specify Dockerfile

# Tag an existing image before pushing (does not duplicate image data)
docker tag myorg/myimage:v1.0.0 myorg/myimage:v1.0.1

# Push to Docker Hub (image becomes available to Runpod as myorg/myimage:v1.0.0)
docker push myorg/myimage:v1.0.0

# Run locally for validation
docker run --rm -it myorg/myimage:v1.0.0 bash
docker run --rm --gpus all myorg/myimage:v1.0.0 bash   # with GPU (requires nvidia-container-toolkit)
docker run --rm -p 8080:80 -e API_KEY=secret myorg/myimage:v1.0.0  # port mapping + env vars

# Debug a running container
docker exec -it CONTAINER_ID /bin/bash

# Inspect
docker images                          # list local images
docker ps -a                           # list all containers (including stopped)
docker logs CONTAINER_ID             # view container output
docker logs -f CONTAINER_ID          # follow logs in real time

# Cleanup
docker rmi myorg/myimage:v1.0.0        # remove an image
docker rm CONTAINER_ID               # remove a stopped container
```

# GitHub CLI — one-time setup

Install `gh` and set up an SSH key (only needed once, if `gh --version` fails or your key
isn't registered yet). Auth verification and commands are in [`github.md`](github.md).

## Install

```bash
# macOS
brew install gh

# Linux (Debian/Ubuntu)
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
     | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update && sudo apt install gh -y

# Linux (Alpine)
apk add github-cli

# Windows (WSL2): use the Linux (Debian/Ubuntu) installer above
```

## SSH Keys

An SSH key identifies your machine as authentic to remote services. Generate one key and
register the public key with each service that requires it — GitHub (via `gh`) and
HuggingFace (via browser).

**Generate a key**

```bash
ssh-keygen -t ed25519 -C "your_email@example.com"
# Saves to ~/.ssh/id_ed25519 (private) and ~/.ssh/id_ed25519.pub (public)
# Press Enter to accept the default path; set a passphrase or leave blank
```

**Add the key to the SSH agent**

```bash
# macOS
eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# macOS — also add to ~/.ssh/config so the key loads automatically on login.
# Create the file if it doesn't exist, and add these lines:
#
#   Host *
#     AddKeysToAgent yes
#     UseKeychain yes
#     IdentityFile ~/.ssh/id_ed25519

# Linux
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Windows (WSL2): use the Linux instructions above
```

**Register the public key with each service** (do this after `gh auth login`, see [`github.md`](github.md)):

```bash
# GitHub — upload via gh CLI (requires auth to be completed first)
gh ssh-key add ~/.ssh/id_ed25519.pub --title "my-machine"

# HuggingFace — paste contents of public key manually in browser
cat ~/.ssh/id_ed25519.pub   # copy this output
# Then add at https://huggingface.co/settings/keys
```

# GitHub CLI

The GitHub CLI (`gh`) is used to manage repositories for Runpod serverless workers. This includes cloning repos into local Docker containers for testing, versioning source code so changes can be tracked and shared with teammates or collaborators, and creating GitHub releases that publish listings to the Runpod Hub. The Hub indexes releases — not commits — so every deployment update requires a new release.

> **Not installed?** One-time install **and SSH-key setup** (generate + register the key) live in [`github-setup.md`](github-setup.md) — skip if `gh --version` works and your key is registered.

## Credentials

```bash
# Interactive login — when prompted, select SSH as the git protocol
gh auth login

# Verify auth
gh auth status
```

## Key Commands

```bash
# Repositories
gh repo create my-worker --public             # create a new public repo (required for Hub)
gh repo clone owner/repo                      # clone a repository over SSH
gh repo clone owner/repo -- --depth 1        # shallow clone
gh repo view owner/repo                       # view repo details and URL

# Releases — the Runpod Hub indexes releases, not commits
# Every update to a Hub listing requires a new GitHub release
gh release create v1.0.0 --title "v1.0.0" --notes "Initial release"   # create a release
gh release create v1.0.1 --title "v1.0.1" --notes "Update model tag"  # update Hub listing
gh release list                               # list all releases
gh release view v1.0.0                        # view release details
```

### Runpod Hub repository structure

A Hub-compatible repository requires these files (in root or `.runpod/` directory):

```
handler.py        # serverless worker implementation
Dockerfile        # container definition
README.md         # documentation shown on Hub listing
.runpod/
  hub.json        # Hub metadata: title, description, category, GPU config, env vars
  tests.json      # test cases run after each release
```

To publish: go to https://console.runpod.io → Hub → Add your repo → enter the GitHub repository URL.

# HuggingFace CLI — one-time setup

Install the `hf` CLI (only needed once, if `hf version` fails). Auth and `hf download`
recipes are in [`huggingface.md`](huggingface.md).

```bash
# macOS / Linux (standalone installer — recommended)
curl -LsSf https://hf.co/cli/install.sh | bash

# macOS (Homebrew)
brew install hf

# Windows (WSL2): use the Linux standalone installer above
```

> **Note:** `pip install huggingface_hub` installs the older Python CLI (`huggingface-cli`),
> which uses different command syntax. Use the standalone `hf` CLI installed above.

# HuggingFace CLI

The HuggingFace CLI (`hf`) is used to download models from the Hub to your local machine so they are cached and available when you build and run the Docker container. For example, to deploy `openai/gpt-oss-20b` to a Runpod serverless endpoint: download the model locally first, build a Docker image that includes or mounts it, validate the container locally, then push the image to Docker Hub for Runpod to pull.

> **Not installed?** One-time install lives in [`huggingface-setup.md`](huggingface-setup.md) — skip if `hf version` already works.
>
> Use the standalone `hf` CLI, **not** `pip install huggingface_hub` (that's the older `huggingface-cli`, different syntax).

## Credentials

Get a token at https://huggingface.co/settings/tokens. Use **write** access for uploading; **read** access is sufficient for downloading public or gated models.

```bash
# Option 1: interactive login (saves token to ~/.cache/huggingface/token, optionally to git credential store)
hf auth login

# Option 2: non-interactive (pass token directly, useful in scripts and pod start commands)
hf auth login --token $HF_TOKEN --add-to-git-credential

# Option 3: environment variable (takes precedence over saved token; to revert, unset the variable)
export HF_TOKEN=hf_...
```

```bash
hf auth whoami      # confirm auth and org memberships
hf auth logout      # delete all locally stored tokens
```

## Key Commands

```bash
# Download a model to a local directory (use --local-dir to control where it lands)
hf download openai/gpt-oss-20b --local-dir ./models/gpt-oss-20b
hf download meta-llama/Llama-3.1-8B --local-dir ./models/llama-3.1-8b

# Download a single file from a model repo
hf download openai/gpt-oss-20b config.json --local-dir ./models/gpt-oss-20b

# Download with glob filters (e.g. only safetensors weights, skip fp16 variants)
hf download stabilityai/stable-diffusion-xl-base-1.0 \
  --include "*.safetensors" --exclude "*.fp16.*" \
  --local-dir ./models/sdxl

# Download a specific revision (commit hash, branch, or tag — append --revision REF)
hf download openai/gpt-oss-20b --revision v1.0 --local-dir ./models/gpt-oss-20b
```

## Troubleshooting

```bash
# Increase download timeout on slow connections (default: 10s)
export HF_HUB_DOWNLOAD_TIMEOUT=30
```

---
name: companion-clis
description: Companion CLIs for Runpod workflows — HuggingFace, GitHub, Docker, and AWS. Use the ComfyUI model-repair guide in runpod-templates instead when an imported ComfyUI workflow lacks model download metadata.
allowed-tools: Bash(hf:*), Bash(gh:*), Bash(docker:*), Bash(aws:*), Bash(ssh-keygen:*), Bash(ssh-add:*), Bash(ssh-agent:*)
compatibility: Linux, macOS, Windows
metadata:
  author: runpod
  version: "1.2.0" # x-release-please-version
license: Apache-2.0
---

# Companion CLIs

Four CLIs commonly needed alongside Runpod. Each has its own **credentials + command reference** in [`reference/`](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.

If the request starts with an imported ComfyUI workflow whose model filenames lack
verified URLs or hashes, route to the
[ComfyUI model-repair guide](../runpod-templates/reference/comfyui-model-repair.md) in
runpod-templates. Return here when the
exact Hugging Face repository/file is already known and the task is simply to
download, cache, or bake that artifact.

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

These CLIs are usually one step inside a larger job. For the whole job the verified example is
in [runpod/golden-paths/README.md](../runpod/golden-paths/README.md) — baking vs mounting a
model ([25](../runpod/golden-paths/25-bake-vs-mount/README.md)), building a minimal image
([22](../runpod/golden-paths/22-minimal-pod-image/README.md)), or moving data to a network
volume ([07](../runpod/golden-paths/07-network-volume-handoff.md)).

These are third-party CLIs on their own release trains, so **`<cli> --help` is authoritative
for flags and subcommands** — the references here cover the Runpod-specific usage and the
traps, not the tool's full surface. Check `--help` before reporting that one of them cannot do
something.

## Windows: Install WSL2 First

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.

## HuggingFace CLI

Download models locally so they're cached for a Docker build/run. Auth and `hf download` recipes: **[reference/huggingface.md](reference/huggingface.md)** (install: [reference/huggingface-setup.md](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).

## GitHub CLI

Manage worker repositories and cut releases. Auth and commands: **[reference/github.md](reference/github.md)** (install + SSH-key setup: [reference/github-setup.md](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).

## Docker

Build, validate, and push images to Docker Hub. Credentials and commands: **[reference/docker.md](reference/docker.md)** (install: [reference/docker-setup.md](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.

## 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](reference/aws.md)** (install: [reference/aws-setup.md](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](reference/aws.md#optional-resumable-volume-transfers-community-tool).