google-colab-cli README

项目的 README,来自 github.com/googlecolab/google-colab-cli。合并为一个 markdown 文件:README.md。

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.

Designed to support seamless developer productivity, headless automation, and AI agent integrations.

Demo

[!NOTE] Platform support: the Colab CLI currently supports Linux and macOS only. Windows is not supported at this time.

[!TIP] Looking for in-notebook, interactive agent-assisted coding instead of a terminal workflow? See the Colab MCP Server.


Key Features


Installation

Install the package using uv (recommended) or standard pip:

# Using uv (recommended)
uv tool install google-colab-cli

# Using pip
pip install google-colab-cli

Quick Start

Run a CPU-based VM runtime, execute some code, and clean up:

# 1. Provision a new session
colab new

# 2. Execute code from stdin
echo 'print("Hello from Google Colab!")' | colab exec

# 3. Stop and release the VM resource
colab stop

[!NOTE] When only one session is active, you can omit the -s, --session option; the CLI automatically knows it.


Command Index

Run colab <command> --help to view specific options, defaults, and detailed help.

Session Management

Command Description
colab new [-s NAME] [--gpu GPU] [--tpu TPU] [--high-mem] Allocate a new CPU, GPU, or TPU VM runtime (optionally high-RAM)
colab sessions List all active sessions currently active on the backend
colab status [-s NAME] Display hardware, machine shape, status, and local metadata for active sessions
colab restart-kernel [-s NAME] Restart the active session's Jupyter kernel
colab stop [-s NAME] Terminate a session VM and release its resources
colab url [-s NAME] [--open] Print or open a browser URL connecting to the active session

Execution

Command Description
colab run [--gpu GPU] [--tpu TPU] [--high-mem] [--keep] SCRIPT [ARGS...] Run a local script on a fresh VM, forwarding arguments, then release it
colab exec [-s NAME] [-f FILE] [--output-image PATH] Execute Python code from stdin, a local .py file, or a .ipynb notebook
colab repl [-s NAME] [--output-image PATH] Start an interactive Python REPL on the VM (exits cleanly on piped EOF)
colab ssh [-s NAME] [--proxy-mode] [-i KEY] [--gpu GPU] [--tpu TPU] [--high-mem] [-- CMD ...] Open an SSH shell to the runtime over WebSocket, run a one-shot remote command (-- CMD), or act as an OpenSSH ProxyCommand bridge for IDE remote-dev

File Operations

Command Description
colab ls [-s NAME] [PATH] List remote files on the VM
colab upload [-s NAME] LOCAL REMOTE Upload a local file to the VM filesystem
colab download [-s NAME] REMOTE LOCAL Download a remote file from the VM filesystem
colab rm [-s NAME] PATH Delete a remote file on the VM filesystem
colab edit [-s NAME] PATH Edit a remote file in-place using your local $EDITOR

Automation & Utilities

Command Description
colab auth [-s NAME] Authenticate the VM for GCP services (BigQuery, GCS, etc.)
colab drivemount [-s NAME] [PATH] Mount Google Drive on the VM (default: /content/drive)
colab install [-s NAME] [-r FILE | PKG...] Install packages on the VM using uv (falls back to pip)
colab log [-s NAME] [-n N] [-o FILE] View or export session history (.ipynb, .md, .txt, .jsonl)
colab usage Show account compute-unit usage rate and balance
colab pay Open the Colab subscription page to manage compute units
colab version Print the installed version of the CLI
colab update [--install] Check for a newer release (and optionally upgrade the CLI in place)

Global Options


Practical Examples

Accelerator Training with Checkpoint Retrieval

Provision an A100 GPU, install requirements, run a local training script, retrieve the resulting model weights, and terminate the VM:

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

Workspace Notebook Execution with Drive Integration

Mount Google Drive, run a local notebook against the VM kernel (outputs are written back into report_output.ipynb), export a Markdown log of the execution, and clean up:

colab new -s analysis
colab drivemount -s analysis
colab exec -s analysis -f report.ipynb
colab log -s analysis -o execution_log.md
colab stop -s analysis

Usage Notes

Ephemeral Accelerator Jobs

Use colab run to run a local script on dedicated hardware without manual session lifecycle management. The CLI handles provisioning, script execution, and immediate VM teardown automatically:

# Run train.py on a T4 GPU and release the VM on completion
colab run --gpu T4 train.py

Shebang Execution Support

To execute a local file directly on a remote accelerator, place the colab run interpreter in the shebang line:

#!/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))

Make the script executable (chmod +x script.py) and run it: ./script.py. The --keep option tells the CLI to preserve the session VM on completion so you can re-execute or inspect logs.


Deep Dive Documentation

For comprehensive architectural overviews and deep-dives into specific CLI sub-systems, refer to the detailed documentation:

To view interactive walkthroughs of eleven real-world automated scenarios, check out the Demo Walkthroughs.


Contributing

Feedback and contributions are welcome! Please read CONTRIBUTING.md for details.


See Colab's Terms of Service and the Google Privacy Policy, which apply to usage of this CLI.

google-colab-cli (googlecolab/google-colab-cli)

正在搜索数据库…

这是什么?一个用于 Google Colab 的命令行界面,可在终端中完成全部操作:分配 CPU、GPU 或 TPU 运行时,运行本地代码,并管理远程文件。
这是笔记本编辑器还是终端工具?它是终端工具,而不是笔记本编辑器。你可以使用 colab new、colab run 和 colab exec 等命令来控制 Colab 虚拟机。
怎样才能把它运行起来?使用 uv(推荐)或 pip 安装该包,然后运行 colab new 分配一台 CPU 虚拟机,运行 colab exec 在其上执行代码,最后运行 colab stop 释放它。
开始之前需要准备什么?Python 以及 uv 或 pip,还需要一个 Colab 账号。T4、A100 等加速器以及高内存配置,需要 Colab Pro 或 Pro+ 权益。
它能在 Windows 上运行吗?不能。该命令行工具仅支持 Linux 和 macOS,目前不支持 Windows。
我的会话令牌保存在磁盘的哪里?保存在 ~/.config/colab-cli/sessions.json 中,全局设置保存在 ~/.config/colab-cli/settings.json 中。两者都可以通过全局参数 --config 更改位置或进行隔离。
我可以获得哪些加速器?可使用 CPU、GPU(T4、L4、G4、H100、A100)和 TPU(v5e1、v6e1)运行时。在支持的加速器上,还可以通过 --high-mem 参数选择可选的高内存配置。
在 GPU 上运行训练脚本最快的方法是什么?使用 colab run 加上加速器参数,例如 colab run --gpu A100 train.py 并附带参数。它会分配一台全新的虚拟机,运行脚本,取回输出文件,然后释放该虚拟机。加上 --keep 可保留虚拟机。
我能用自己的编辑器编辑虚拟机上的文件吗?可以。colab edit 会使用你本地的 $EDITOR 直接打开远程文件进行编辑。
我的 IDE 能连接到运行时进行远程开发吗?可以。colab ssh 可以充当 OpenSSH ProxyCommand 桥接器,使 IDE 的远程开发工具能够连接到 Colab 虚拟机。
有没有可以在笔记本内使用的、由智能体辅助编程的替代方案?README 推荐使用独立的 Colab MCP Server,在笔记本内进行交互式的智能体辅助编程,而不是在终端中工作。
大小
1.4 MB
星标
2.5K
更新
提交Nov 18
时长
7个月
提交 · 90 天