Google’s Low‑Key Launch: The Google Colab CLI Brings Notebooks to the Terminal

Overview

Google Colab CLI moves the usual browser‑based Colab workflow to the command line, allowing users to create a VM, execute code, and shut down the VM with three simple commands.

colab new
echo "print('Hello from Google Colab!')" | colab exec
colab stop

The tool targets AI‑agent engineers and automation script writers, offering features such as one‑click VM provisioning (CPU, GPU T4/L4/G4/H100/A100, TPU v5e1/v6e1), remote execution of local .py or .ipynb files without upload, kernel state persistence across colab exec calls, a built‑in keep‑alive daemon, a shebang syntax that turns a Python script into a GPU‑enabled executable, and one‑click export of notebooks to .ipynb/.md/.jsonl.

Installation & Authentication

Supported on Linux and macOS. Recommended installation with uv tool install google-colab-cli (or pip install google-colab-cli). Verify with colab version.

Authentication uses Application Default Credentials with four required scopes; the command is:

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

Missing any scope results in 401/403 errors. The hidden colab whoami command can show the current token scopes.

Typical Usage

Three‑step workflow:

# 1. Create a session
colab new -s mywork

# 2. Run a local script
colab exec -s mywork -f train.py

# 3. Stop the VM
colab stop -s mywork

For a single‑run scenario, colab run --gpu T4 train.py combines new, exec, and stop, preserving exit codes for CI pipelines.

Shebang GPU Scripts

Placing #!/usr/bin/env -S colab run --gpu L4 --keep at the top of a Python file makes it executable on a remote GPU:

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

After chmod +x script.py, running ./script.py executes on the L4 GPU.

Kernel Persistence and File Operations

Repeated colab exec calls within the same session share the Jupyter kernel, keeping imported libraries and loaded models in memory. The state is cleared only by colab stop or colab restart-kernel.

File commands include colab ls, colab upload, colab download, colab drivemount, colab auth, and colab install. The latter two require interactive TTY, so they are unsuitable for fully automated agents.

Real‑World Example: Fine‑tuning Gemma 3‑1B

The repository’s examples/finetune_run.py fine‑tunes Gemma 3‑1B on a Text‑to‑SQL dataset using 4‑bit QLoRA, LoRA adapters (r=16, alpha=32), and SFTTrainer for 60 steps. The workflow injects a HuggingFace token, verifies it, and runs the script via colab exec -f finetune_run.py. The CLI enables the entire process with a single command line.

Relation to Other Google Tools

Colab CLI focuses on terminal automation, while Colab MCP Server supports interactive agents inside notebooks, and Antigravity provides a full‑featured Agent IDE. Users of Cursor or Claude Code are advised to start with the CLI for terminal‑based GPU access.

Conclusion

The CLI is ideal for ML experimenters who find notebooks heavyweight, AI‑agent developers needing cloud GPU from scripts, and macOS users without local GPUs. It does not support Windows, requires a Colab subscription for GPU access, and some commands need manual TTY interaction.