google-colab-cli README

The project's README from github.com/googlecolab/google-colab-cli. As one markdown file: 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)

Searching Database…

What is this?A command-line interface for Google Colab that provisions CPU, GPU or TPU runtimes, runs local code and manages remote files, all from your terminal.
Is this a notebook editor or a terminal tool?It is a terminal tool, not a notebook editor. You control Colab VMs with commands such as colab new, colab run and colab exec.
How do I get it running?Install the package with uv (recommended) or pip, then run colab new to allocate a CPU VM, colab exec to run code on it, and colab stop to release it.
What do I need before I start?Python with uv or pip, and a Colab account. Accelerators such as T4 and A100, and high-RAM shapes, need Colab Pro or Pro+ entitlement.
Does it run on Windows?No. The CLI supports Linux and macOS only, and Windows is not supported at this time.
Where are my session tokens kept on disk?In ~/.config/colab-cli/sessions.json, with global settings in ~/.config/colab-cli/settings.json. Both can be relocated or isolated with the global --config flag.
Which accelerators can I get?CPU, GPU (T4, L4, G4, H100, A100) and TPU (v5e1, v6e1) runtimes, with an optional high-RAM shape via the --high-mem flag on supported accelerators.
What is the quickest way to run a training script on a GPU?Use colab run with an accelerator flag, for example colab run --gpu A100 train.py with arguments. It provisions a fresh VM, runs the script, retrieves output files and tears the VM down. Add --keep to keep the VM.
Can I edit a file on the VM in my own editor?Yes. colab edit opens a remote file in place using your local $EDITOR.
Can my IDE connect to the runtime for remote development?Yes. colab ssh can act as an OpenSSH ProxyCommand bridge, so IDE remote-development tools can attach to a Colab VM.
Is there an in-notebook alternative for agent-assisted coding?The README points to the separate Colab MCP Server for in-notebook, interactive agent-assisted coding instead of a terminal workflow.
Size
1.4 MB
Stars
2.5K
Updated
CommitNov 18
Age
7mo
Commits · 90 Days