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.

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

 Instant VM Provisioning: Spin up CPU, GPU (T4, L4, G4, H100, A100), or TPU (v5e1, v6e1) runtimes in seconds.
 Robust Code Execution: Run local Python scripts, Jupyter Notebooks (.ipynb), or piped stdin code; launch interactive REPLs or raw TTY console shells.
 Ephemeral Job Runner (colab run): Provision a fresh VM, execute a local script with forwarded arguments, retrieve output files, and automatically tear down the runtime in a single command.
 Activity-Based Liveness: Sessions stay alive as long as the kernel is active, with the Colab backend automatically maintaining liveness.
 Seamless Workspace Automation: Mount Google Drive, authenticate Google Cloud Platform (GCP) credentials, and install dependencies with high-performance uv package management.
 State & Log Archival: Inspect local session states or export interactive history logs to standard Jupyter Notebooks, Markdown, or structured JSONL.

---

 Installation

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

bash
 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:

bash
 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  --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 i

Top issues

Discussions