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.mov
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.
- 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 pipedstdincode; 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
uvpackage management. - State & Log Archival: Inspect local session states or export interactive history logs to standard Jupyter Notebooks, Markdown, or structured JSONL.
Install the package using uv (recommended) or standard pip:
# Using uv (recommended)
uv tool install google-colab-cli
# Using pip
pip install google-colab-cliRun 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 stopNote
When only one session is active, you can omit the -s, --session option;
the CLI automatically knows it.
Run colab <command> --help to view specific options, defaults, and detailed help.
| 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 |
| 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 console [-s NAME] |
Connect to a raw interactive TTY shell (tmux) on the remote VM |
colab ssh [-s NAME] [--proxy-mode] [-i KEY] [--gpu GPU] [--tpu TPU] [--high-mem] |
Open an SSH shell to the runtime over WebSocket, or act as an OpenSSH ProxyCommand bridge for IDE remote-dev |
| 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 |
| 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) |
--auth {oauth2,adc}— Authentication strategy for the Colab API (default:adc).-c, --client-oauth-config PATH— Path to public OAuth client credentials configuration (default:~/.colab-cli-oauth-config.json).--config PATH— Path to local session metadata storage (default:~/.config/colab-cli/sessions.json).--logtostderr— Direct debug logging output to stderr.
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 trainerMount 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- Machine shape: Use
--high-memwithcolab new,colab run, orcolab ssh(when auto-creating a runtime) to request a high-RAM machine shape. Requires Colab Pro or Pro+ entitlement for supported accelerators (CPU, T4, A100, etc.). L4 and TPU runtimes ignore this flag because they only offer one shape. Machine shape is shown incolab sessionsandcolab status. - TTY Requirements: The interactive commands
replandconsolerequire a local TTY. When running inside automated scripts or pipelines, make sure to pipe stdin (e.g.,echo "print(1)" | colab repl) to trigger non-interactive execution modes. - Transparent Code Execution: When calling
colab exec -f file.py, the CLI reads the file locally and transmits its content to the remote kernel. You do not need to manually upload files before execution. - Storage & State Paths: Session tokens and metadata are stored at
~/.config/colab-cli/sessions.json. Global CLI settings are located at~/.config/colab-cli/settings.json. These can be customized or isolated via the global--configflag.
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.pyTo 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.
For comprehensive architectural overviews and deep-dives into specific CLI sub-systems, refer to the detailed documentation:
- Session Management Architecture
- Interactive & Non-Interactive Execution Design
- File Management & Jupyter Contents API
- Authentication Providers & VM Automation
- Ephemeral Job Runner Design
To view interactive walkthroughs of eleven real-world automated scenarios, check out the Demo Walkthroughs.
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.