runpod/runpodctl

runpodctl의 기능

runpodctl은 RunPod의 명령줄 클라이언트로, GPU 기반 컨테이너(pods라고 함)와 서버리스 추론 엔드포인트를 생성하고 관리할 수 있습니다. 이 도구를 사용하면 터미널에서 리소스 생성, 시작, 정지, 삭제, 검사, 서버리스 함수 호출, 파일 전송을 모두 수행할 수 있습니다.

사용 대상

• 훈련이나 실험을 위해 즉시 GPU 머신이 필요한 AI 연구자 / 개발자
• 서버리스 엔드포인트로 추론 모델을 배포하고 빠르게 테스트하거나 모니터링하고 싶은 ML 엔지니어
• HTTP 호출을 직접 작성하지 않고도 컴퓨팅 자원을 프로그래밍 방식으로 프로비저닝이 필요한 자동화 스크립트 또는 AI 에이전트

핵심 기능

영역	명령어 (명사-동사 형식)	수행 가능한 작업
Pod 관리	runpodctl pod list/get/create/update/start/stop/delete	기존 GPU 포드 목록 조회, 포드 정보 확인, Docker 이미지에서 새 포드 생성, 구성 변경, 라이프사이클 제어
서버리스 엔드포인트	runpodctl serverless list/get/create/update/delete/run/status/health	"서버리스" 추론 서비스 관리, JSON 페이로드로 실행, 작업 상태 확인, 워커 상태 점검
준비 완료 대기	--wait (pod create 또는 serverless create에서 사용)	포드의 SSH 접속 가능 또는 서버리스 워커가 ready/running 상태가 될 때까지 블로킹. 수동 폴링 루프를 피할 수 있음
파일 전송	runpodctl send <file> / runpodctl receive <code>	API 키 없이 피어 투 피어 도구 croc를 사용해 마シン 간 파일 전송
출력 형식	`--output=json	yaml
에러 처리	stderr에 일관된 JSON 에러 객체와 안정적인 code 필드 포함	스크립트는 자유형 메시지를 파싱하는 대신 에러 코드(not_found, usage_error, wait_timeout 등)를 기반으로 분기 가능

일반적인 워크플로우 (빠른 시작)

# 1️⃣ RunPod API 키 한 번 저장
runpodctl config --apiKey=YOUR_KEY

# 2️⃣ 현재 포드 목록 보기
runpodctl pod list

# 3️⃣ 새 GPU 포드 생성 (예: A100에 PyTorch 이미지)
runpodctl pod create \
  --image=runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04 \
  --gpu-id=NVIDIA_A100

# 4️⃣ 사용 후 정지 및 삭제
runpodctl pod stop <pod_id>
runpodctl pod delete <pod_id>

서버리스 엔드포인트에도 동일한 패턴이 적용 가능. 예: runpodctl serverless run <id> --input '{"prompt":"hello"}'

설치 옵션

플랫폼	명령어
Linux/macOS (WSL 포함)	wget -qO- cli.runpod.net | sudo bash
macOS (Homebrew)	brew install runpod/runpodctl/runpodctl
Windows PowerShell	wget https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-windows-amd64.exe -O runpodctl.exe
Conda / Mamba / Pixi	conda install -c conda-forge runpodctl (또는 mamba, pixi global install)

개발자에게 중요한 설계 사항

• JSON 우선 출력: 성공한 모든 명령어는 stdout에 단일 JSON 객체를 출력합니다. 이는 다른 프로그램이나 LLM 기반 에이전트에서 쉽게 사용할 수 있도록 합니다.
• stdout / stderr 분리: 데이터(포드 정보, 작업 페이로드)는 stdout으로, 진행 메시지와 에러 객체는 stderr로 전송됩니다. 스트림 혼합을 방지합니다.
• 안정적인 에러 코드: 모든 에러에는 소문자 code 필드(예: not_found, rate_limited)가 포함됩니다. 스크립트는 HTTP 상태나 자유형 텍스트가 아닌 이 필드를 기반으로 분기해야 합니다.
• 대기 세미틱스: --wait는 리소스가 사용 가능해질 때까지 블로킹합니다(포드는 SSH 접속 가능, 서버리스는 적어도 하나의 워커가 준비됨). 타임아웃은 설정 가능(--wait-timeout). 대기를 중단해도 리소스는 삭제되지 않으며, CLI는 리소스 ID를 반환하여 나중에 정리할 수 있습니다.
• 숨겨진 동기식 엔드포인트 없음: CLI는 항상 비동기식 /run API를 사용하고 /status를 폴링합니다. /runsync 엔드포인트의 단점(청구 오류, 결과 보존 기간 짧음)을 피합니다.

사용하지 않아도 되는 경우

RunPod을 웹 UI 또는 고수준 SDK만 사용하는 경우 runpodctl 설치는 거의 가치가 없습니다. CI 파이프라인, 원격 셸, 또는 자율형 AI 에이전트의 일부로 가볍고 스크립트 가능한 인터페이스가 필요한 경우에만 이 도구의 진가가 발휘됩니다.

---

위 모든 내용은 프로젝트의 README에서 직접 인용되었으며, 추가 기능은 추측되지 않았습니다.