Google Colab CLI 실전 가이드: 터미널에서 A100 GPU 1줄로 띄우는 법

노트북 켜고, 런타임 연결하고, 셀 하나씩 실행하고... 매번 브라우저 열기 귀찮았다면 딱 맞는 도구 나왔습니다.

---

→ 핵심 요약

→ Google Colab CLI, 2026년 6월 5일 공식 출시 (Apache 2.0 오픈소스)
→ 로컬 터미널에서 원격 Colab 런타임을 명령어로 직접 제어
→ GPU: T4, L4, G4, A100, H100 / TPU: v5e1, v6e1 — 플래그 한 줄로 프로비저닝
→ colab exec로 로컬 .py 파일을 원격 GPU에서 바로 실행
→ colab run — VM 생성 → 스크립트 실행 → 아티팩트 회수 → VM 종료 자동화
→ Claude Code, Codex, Antigravity 등 AI 에이전트 터미널 통합 지원
→ COLAB_SKILL.md 번들 포함 — 에이전트가 CLI를 즉시 이해하고 사용 가능
→ Linux / macOS 지원, Windows 미지원
→ Colab MCP Server(3월 출시)와 별도 도구 — 용도 다름

---

왜 지금 이게 필요한가

기존 Colab 브라우저 방식의 한계는 명확합니다. 파이프라인 자동화가 안 되고, AI 에이전트가 직접 접근하기 어렵고, CI/CD 연동도 번거롭습니다.

Colab CLI 이전에는 Colab GPU 컴퓨트를 쓰려면 반드시 브라우저 세션이 필요했습니다. 노트북을 열고, 런타임을 연결하고, 셀을 순서대로 실행하고, 결과물을 수동으로 다운로드해야 했죠. 인터랙티브 개발에는 충분하지만 파이프라인, 스크립트, 자율 에이전트와는 잘 맞지 않았습니다.

Colab CLI는 로컬 터미널과 원격 Colab 런타임 사이의 간극을 메우는 제로 마찰 실행 플랫폼입니다. 개발자와 AI 에이전트 모두를 위해 설계됐습니다.

---

설치

# uv 방식 (권장)
uv tool install google-colab-cli

# pip 방식
pip install google-colab-cli

# GitHub 직접 설치
uv tool install git+https://github.com/googlecolab/google-colab-cli

설치 후 Google 계정 인증 1회:

colab auth login
# 브라우저 OAuth2 인증 → 이후 로컬 자격증명 저장

⚠️ 플랫폼 주의: Linux / macOS만 지원합니다. Windows는 현재 미지원.

---

실전 1 — 기본 세션 시작부터 종료까지

# 1. CPU 세션 프로비저닝
colab new

# 2. 원격 VM에서 코드 실행 (stdin)
echo "print('Hello from Colab VM!')" | colab exec

# 3. 로컬 .py 파일을 원격에서 실행
colab exec -f train.py

# 4. VM 상태 확인
colab status

# 5. 세션 종료 및 VM 반납
colab stop

💡 개념 박스 — colab exec의 동작 방식
colab exec는 파일을 로컬에서 읽어서 내용을 원격 VM으로 전송합니다. 별도의 업로드 단계가 필요 없습니다. 즉, 로컬 파일 수정 → 즉시 원격 실행이 가능합니다.

---

실전 2 — GPU / TPU 프로비저닝

세션 생성 시 가속기를 요청합니다. CPU가 기본값이며, GPU는 T4, L4, A100, H100, TPU는 v5e1, v6e1을 지원합니다.

# T4 GPU (무료 플랜에서 가능)
colab new --gpu T4

# A100 GPU (Colab Pro+ 이상)
colab new --gpu A100

# H100 GPU
colab new --gpu H100

# TPU v6e
colab new --tpu v6e1

# 세션에 이름 붙이기 (여러 세션 관리 시)
colab new --gpu A100 -s my-training-job

여러 세션을 동시에 운영할 때:

# 세션 목록 확인
colab list

# 특정 세션 지정
colab exec -s my-training-job -f train.py

세션이 하나뿐이면 -s 옵션 생략 가능합니다.

---

실전 3 — 파일 주고받기

# 로컬 → 원격 업로드
colab upload dataset.csv

# 원격 → 로컬 다운로드
colab download model.pt
colab download results/

# 원격 파일 목록 확인
colab ls /content/

# 원격 파일 삭제
colab rm /content/temp_file.pkl

# 세션 히스토리를 .ipynb 로그로 내보내기
colab log --output session_replay.ipynb

---

실전 4 — colab run: 일회성 작업 자동화

colab run은 에페머럴(일회성) 잡 러너입니다. 새 VM을 프로비저닝하고, 로컬 스크립트를 인수와 함께 실행하고, 출력 파일을 회수한 뒤, 런타임을 자동으로 종료합니다. 단 하나의 명령어로 전체 과정이 처리됩니다.

# 기본 사용
colab run train.py

# GPU 지정 + 인수 전달
colab run --gpu A100 train.py --epochs 10 --lr 0.001

# 출력 파일 자동 회수
colab run --gpu A100 --output ./results train.py

# 자동화 파이프라인 내에서 (stdin 파이프)
echo "import torch; print(torch.cuda.get_device_name(0))" | colab r

colab run이 colab new + exec + download + stop 4단계를 하나로 압축합니다. CI/CD나 크론 잡에 붙이기 딱 좋습니다.

---

실전 5 — 인터랙티브 세션

# Python REPL (인터랙티브 디버깅)
colab repl

# Raw TTY 쉘 (bash 명령어 직접 실행)
colab console

# 패키지 설치 (uv 기반, 속도 빠름)
colab install numpy pandas scikit-learn

---

실전 6 — Claude Code와 연동

CLI에는 COLAB_SKILL.md가 번들로 포함돼 있어 에이전트가 CLI 사용법을 즉시 이해하고 실행할 수 있습니다. Claude Code 기준 연동 예시:

# Claude Code 터미널에서
# COLAB_SKILL.md를 컨텍스트로 전달하면 Claude가 자동으로 CLI 사용

# 예: Gemma 3 1B QLoRA 파인튜닝 자동화
# Antigravity 또는 Claude Code에게 아래와 같이 지시
"Use the Colab CLI to fine-tune Gemma 3 1B on a Text-to-SQL dataset using QLoRA on an A100."

Claude Code가 실제로 실행하는 순서:

colab new --gpu A100 -s finetune-job
colab upload train_data.jsonl
colab exec -s finetune-job -f qlora_train.py
colab download -s finetune-job ./output/model_weights/
colab stop -s finetune-job

💡 개념 박스 — CLI vs Colab MCP Server
3월에 출시된 Colab MCP Server는 MCP 프로토콜 기반으로 Claude·Gemini 같은 MCP 지원 환경에서 구조화된 tool call 방식으로 Colab에 접근합니다. Colab CLI는 쉘 스크립트, CI/CD 파이프라인, Makefile, 터미널 기반 에이전트 등 MCP를 쓰지 않는 모든 환경에서 더 단순하고 이식성 높은 선택지입니다.

---

브라우저 Colab vs CLI 비교

항목 브라우저 Colab Colab CLI

인터페이스	웹 노트북 UI	로컬 터미널
가속기 선택	브라우저 런타임 메뉴	--gpu / --tpu 플래그
AI 에이전트 사용	수동 (UI 조작)	터미널 에이전트 직접 호출
로컬 스크립트 실행	셀에 붙여넣기 또는 업로드	colab exec -f script.py
아티팩트 회수	수동 다운로드 또는 Drive	colab download, colab log
패키지 설치	!pip inside cell	colab install (uv 기반)
세션 자동 종료	브라우저 관리	colab run으로 자동화
CI/CD 연동	어려움	네이티브 지원

---

✅ 이럴 때 쓰세요

✅ ML 학습 파이프라인 자동화 (크론 잡, CI/CD)
✅ Claude Code / Codex 에이전트에게 GPU 작업 위임
✅ 로컬 .py 파일 수정 후 즉시 원격 GPU에서 검증
✅ 대용량 모델 체크포인트를 원격에서 생성 후 회수
✅ QLoRA 파인튜닝처럼 긴 학습 작업을 에이전트로 위임

❌ 이건 주의

❌ Windows 환경 — 현재 미지원 (Linux/macOS만)
❌ 노트북 UI가 필요한 인터랙티브 EDA — 브라우저 Colab이 더 적합
❌ 가속기 가용성은 현재 Colab 플랜에 따라 다름 — A100/H100은 Pro+ 이상
❌ 자동화 파이프라인에서 colab exec 쓸 때 stdin 파이프 확인 필수

---