【備忘録】Colab CLIの概要を確認する ― ターミナルからColabのGPU/TPUを扱うツールを整理

Posted at 2026-10-29

はじめに

Google Colabは、ブラウザでNotebookを開いて使うものというイメージが強いです。

2026年6月5日、Google Developers Blogで Colab CLI が発表されました。ローカルのターミナルからColabのランタイム（CPU / GPU / TPU）を確保し、手元のスクリプトをそのまま実行できるコマンドラインツールです。開発者だけでなく、AIエージェントから使うことも前提にした作りになっています。

ただ、触ってみる前に「何ができるのか」「どこに注意すればよいのか」を一度整理しておきたいと思いました。この記事では、公式リポジトリのREADME・ドキュメント・ソースコードを読みながら、Colab CLIの概要を確認した内容をまとめます。

※本記事は2026-10-26時点の個人の整理メモです。確認したのは公式リポジトリ googlecolab/google-colab-cli の v0.7.5（PyPI公開日：2026-10-20）です。Colab CLIは公開から日が浅く、更新が頻繁なツールです。コマンド名、既定値、対応OS、課金の扱いなどは変わる可能性があるため、試す前に必ず公式のREADMEと --help を確認してください。

※本記事の図解は公開情報をもとに筆者が独自に作成したものであり、Google公式の資料ではありません。

この記事で扱う範囲

この記事では、次の範囲に絞ります。

Colab CLIが何をつなぐツールなのか（全体像）
用意されているコマンドの整理
2つの代表的な使い方（セッション型 / 使い捨て型）
認証とAIエージェント向けの仕組み
試す前に押さえておきたい注意点

一方で、実際にGPUで学習を回した結果や、料金の詳しい比較、Colab MCP Serverとの詳しい比較は扱いません。まずは「概要を確認して、試す前の準備をする」段階のメモです。

Colab CLIの全体像

READMEの冒頭では、Colab CLIは次のように説明されています。

A command-line interface for Google Colab. Provision high-performance CPU, GPU, and TPU runtimes, execute local code, manage remote files, and orchestrate automated cloud pipelines — directly from your terminal.

ざっくり言うと、ローカルのターミナルとColabのランタイム（VM）をつなぐツール と捉えると理解しやすそうです。

ポイントを整理すると次のとおりです。

項目	内容
提供元	Google（`googlecolab/google-colab-cli`、Apache License 2.0）
インストール	`uv tool install google-colab-cli` または `pip install google-colab-cli`
Python	3.12以上（PyPIのメタデータ）
対応OS	READMEでは Linux / macOS のみ（Windowsは非対応と記載）
確保できるランタイム	CPU、GPU（T4 / L4 / G4 / H100 / A100）、TPU（v5e1 / v6e1）
想定する使い手	開発者、ヘッドレスな自動化、AIエージェント

リモート側の実体は Jupyterカーネルが動くVM です。同梱のエージェント向けスキルには「セッション＝借りたVM上で動いているJupyterカーネル」と書かれていて、colab exec を複数回呼んでも同じカーネルに接続し直すため、importや変数が残ります。作業ディレクトリの既定は /content で、ブラウザ版Colabと同じ感覚で扱えます。

👉 「ブラウザでNotebookを開かずに、Colabの計算資源をターミナルから使う」ためのツールと整理しやすいです。

なお、Notebookの中でエージェントと対話的にコーディングしたい場合は、別ツールの Colab MCP Server が案内されています。ターミナル中心の作業ならCLI、Notebook中心ならMCP Server、という住み分けのようです。

コマンドを4つのグループで整理する

READMEのCommand Indexには20以上のコマンドが並んでいます。最初は多く見えますが、役割で分けると4グループに整理できます。

セッション管理

コマンド	役割
`colab new [--gpu GPU] [--tpu TPU] [--high-mem]`	CPU / GPU / TPUのVMを確保する
`colab sessions` / `colab status`	セッション一覧・ハードウェアや状態の確認
`colab restart-kernel`	カーネルを再起動する
`colab stop`	VMを停止してリソースを解放する
`colab url [--open]`	セッションにつながるブラウザURLを表示・オープン

実行

コマンド	役割
`colab run SCRIPT [ARGS...]`	新しいVMでスクリプトを実行し、終わったら解放する
`colab exec [-f FILE]`	stdin / `.py` / `.ipynb` をカーネルで実行する
`colab repl`	対話的なPython REPL
`colab console`	tmuxベースの生のTTYシェル
`colab ssh`	WebSocket経由のSSH接続（IDEのリモート開発用 `ProxyCommand` にもなる）

ファイル操作

colab ls / upload / download / rm / edit が用意されています。edit はリモートのファイルを手元の $EDITOR で編集するコマンドです。

自動化・ユーティリティ

コマンド	役割
`colab auth`	VM側でGCPサービス（BigQuery、GCSなど）の認証を行う
`colab drivemount`	Google Driveをマウントする（既定は `/content/drive`）
`colab install`	`uv` でパッケージを入れる（使えない場合は `pip`）
`colab log [-o FILE]`	セッションの実行履歴を表示・書き出す（`.ipynb` / `.md` / `.txt` / `.jsonl`）
`colab usage` / `colab pay`	コンピューティングユニットの使用状況確認 / 購入ページを開く
`colab version` / `colab update`	バージョン確認 / 更新チェック

注意したいのは colab log です。名前から「学習ログのファイルを回収するコマンド」と思いがちですが、実際は このセッションで実行したコードと出力の履歴 をNotebookやMarkdownとして書き出すものです。学習スクリプトが書いたログファイルを持ってくるなら colab download を使います。

👉 exec の結果をあとからNotebookとして残せるのは、エージェントに作業させたときの記録にも使えそうです。

2つの使い方 ― セッション型と使い捨て型

READMEの例を見ていくと、使い方は大きく2つに分かれると整理できます。

A. セッション型（試行錯誤向け）

VMを確保して、何度かコマンドを送り、最後に自分で止める使い方です。READMEにある、A100で学習してモデルを回収する例は次のとおりです。

colab new -s trainer --gpu A100
colab install -s trainer torch transformers
colab exec -s trainer -f train.py
colab download -s trainer checkpoints/model.bin ./model.bin
colab stop -s trainer

-s はセッション名です。READMEによると、アクティブなセッションが1つだけなら -s は省略できます。

また、colab exec -f train.py はローカルのファイルを読んでその内容をカーネルに送るので、事前に upload しておく必要はありません。ここは最初に読んだとき勘違いしやすいポイントでした。

B. 使い捨て型（バッチ・自動化向け）

colab run は、新しいVMの確保 → スクリプト実行 → VMの解放をコマンド1つで行います。

# T4 GPUで train.py を実行し、完了したらVMを解放する
colab run --gpu T4 train.py

READMEと実装を見ると、--keep を付けない限り、スクリプトが正常に終わった場合もエラーで終わった場合も、最後にVMの解放処理が行われます。ただし解放処理はベストエフォートで、途中で失敗してもエラーとしては表示されません。自動で解放される使い方でも、必要に応じて colab sessions でセッションが残っていないか確認しておくと安心です。

--keep を付けると、終了後もVMを残せます。さらに、スクリプトのshebangに書いて直接実行する使い方も紹介されています。

#!/usr/bin/env -S colab run --gpu L4 --keep
import torch

print("L4 GPU Available:", torch.cuda.is_available())
print("Device Name:", torch.cuda.get_device_name(0))

chmod +x script.py してから ./script.py で、手元のファイルをL4 GPU上で実行できる、という形です。

👉 何度も触りながら進めるならセッション型、決まった処理を流すなら colab run、と使い分けると整理しやすそうです。

認証とAIエージェント向けの仕組み

認証は `oauth2` と `adc` の2種類

Colab CLIがColabのバックエンドと通信するときの認証は、グローバルオプション --auth で選びます。サブコマンドより前に書く点に注意です（例: colab --auth=adc new）。

oauth2 … 表示されたURLでサインインし、表示されたコードを貼り付ける方式（v0.6.0でlocalhostコールバックからこの方式に変更）。トークンは ~/.config/colab-cli/token.json にキャッシュされる
adc … Application Default Credentials。gcloud auth application-default login などで用意した認証情報を使う

なお、コマンド一覧にある colab auth は、ColabのVM内からGoogle Cloudサービス（BigQuery、GCSなど）を使うための認証コマンドです。CLI自体がColabのバックエンドに接続するときの --auth とは役割が異なります。

adc を使う場合、同梱スキルとデモ資料では次の4つのスコープを付けてログインし直すよう案内されています。

gcloud auth application-default login \
  --scopes=openid,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/colaboratory

ここで1つ気になった点があります。既定値の記載が資料によって違います。

資料	既定値の記載
README（Global Options）	`adc`
同梱スキル `skills/colab-operator/SKILL.md`	`adc`
`docs/04_automation_and_utility.md`	`oauth2`
ソースコード `src/colab_cli/cli.py`	`AuthProvider.OAUTH2`（= `oauth2`）

v0.7.5時点のコードでは oauth2 が既定でした。どちらで動くかを曖昧にしないために、当面は --auth=adc や --auth=oauth2 を 明示して使う のが安全そうです。

エージェント向けスキルを同梱

リポジトリには skills/colab-operator/SKILL.md が含まれていて、エージェントがColab CLIを操作するときの考え方がまとまっています。

セッションは課金対象のVMであり、new で確保して stop で解放する
カーネルの状態は exec をまたいで残るので、毎回importし直さなくてよい
認証エラー（401 / 403）が出たときは、認証情報・権限・スコープなどを確認する

発表時は COLAB_SKILL.md というスキルファイルとして同梱されていましたが、v0.7.0で skills/colab-operator/SKILL.md に移されています。公式ブログではAntigravityエージェントでの例（Gemmaのファインチューニング）が紹介されていて、Claude CodeやCodexなど、ターミナルを使える他のエージェントからも使えるとされています。

👉 人間向けのREADMEとは別に「エージェント向けの取扱説明書」が同梱されている点が、このツールの特徴だと捉えると理解しやすいです。

試す前に押さえておきたい確認ポイント

READMEとコードを読んで、実際に試す前に確認しておきたいと思った点をまとめます。

1. VMは自分で `stop` する前提で使う

READMEには「カーネルがアクティブな間は、Colabのバックエンドがセッションを維持する」と書かれています（v0.7.3以降はCLI側のkeep-aliveをやめ、バックエンド側に任せる形になりました）。一方で、アイドル状態がどのくらい続くと回収されるかはREADMEには書かれていません。スキルファイルには「colab new は課金対象のVMを確保する」と明記されているので、自動で消えることを当てにせず、使い終わったら自分で止めるのが安全です。セッション型で使ったら、最後に colab stop を忘れないようにします。colab sessions で、止め忘れたセッションが残っていないかも確認できます。コンピューティングユニットの状況は colab usage で確認できます。

2. 認証方式は明示する

前述のとおり、--auth の既定値は資料によって記載が異なります。エージェントに使わせる場合は、ブラウザ操作が不要な adc が勧められています。

3. 対応OSはLinux / macOS（README上）

READMEでは「現時点ではLinuxとmacOSのみ、Windowsは非対応」と書かれています。一方、2026年10月にはWindows向けの修正コミット（termiosまわりのクラッシュ修正、SSHコマンドの起動処理の修正など）も入っています。ただしSSHまわりの修正はv0.7.5より後のコミットで、READMEの記載もまだ変わっていません。対応が進んでいる途中と捉えるのがよさそうです。Windowsで使いたい場合は、当面はWSLなどを検討するのが無難そうです。

4. `--gpu` / `--tpu` の名前は正確に

ソースコード（src/colab_cli/commands/session.py）を見ると、v0.7.5の実装では、--gpu に対応表にない名前を渡すとエラーにならず A100として解釈 されます。同様に --tpu も、v5e1 以外の値はすべて v6e1 として解釈されます。ただし、実際に割り当てられるかどうかは利用資格やリソース状況によって異なります。意図しない指定を避けるため、GPUは T4 / L4 / G4 / H100 / A100、TPUは v5e1 / v6e1 のいずれかを正確に入力するのがよさそうです。また、--high-mem はColab Pro / Pro+ の権利が必要とされています。

5. 変化が速い

2026年6月の発表から約4か月で v0.7.5 まで進んでいて、その間に認証方式の変更（v0.6.0）、colab ssh の追加（v0.7.0）、colab usage の追加などがありました。ネット上の記事（この記事も含めて）の書き方が古くなっている可能性があるので、colab <command> --help を一次情報として確認するのが確実です。

また、名前が似た非公式ツールもあるため、インストール時はパッケージ名が google-colab-cli であることを確認しておくと安心です。

まとめ

Colab CLIは、ローカルのターミナルとColabのランタイム（CPU / GPU / TPU）をつなぐ Google公式のコマンドラインツール
コマンドは「セッション管理」「実行」「ファイル操作」「自動化・ユーティリティ」の4グループで整理すると見通しがよい
使い方は、new → exec → stop の セッション型 と、colab run の 使い捨て型 の2つ
エージェント向けの SKILL.md が同梱されていて、AIエージェントから使うことも前提にしている
試す前には、VMの停止忘れ、認証方式の明示、対応OS、GPU/TPU名の指定、バージョン差分を確認しておく

一言でまとめると、「ColabのGPUを、Notebookを開かずにスクリプトやエージェントから使うための入口」 と整理できそうです。次は実際にT4で小さなスクリプトを colab run してみて、セッション型との使い勝手の違いを確認してみたいと思います。

参考（公式情報）

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up