Colab CLI – Control Google Colab from your terminal and automate GPU/TPU jobs with AI agents

Google Colab CLI: Run Colab from your terminal and automate with AI agents

TL;DR

  • Colab CLI brings Google Colab runtimes to your terminal so developers and automation agents can provision GPUs/TPUs, run Python, move files and capture replayable logs — all from scripts and CI.
  • Who benefits: data scientists prototyping on laptops, MLOps teams adding quick GPU jobs to CI, and teams experimenting with agent-driven automation for model tuning.
  • One caveat: Colab is a managed, quota-backed runtime — great for experiments and CI tests, not a substitute for production clusters.

Who should read this: data scientists, MLOps engineers, developer teams evaluating AI automation, and technical leaders weighing the tradeoffs of using Colab for prototyping and lightweight production tasks.

What the Colab CLI does — fast

The Colab CLI connects your local shell to Google Colab runtimes so you can run code on cloud GPUs or TPUs without opening a browser. It’s open-source (Apache 2.0) and installs in one line from the googlecolab/google-colab-cli on GitHub. The focus is on scripted, reproducible workflows — including workflows that let automation agents control runs — so you can provision a runtime, execute a script, download artifacts and export a replayable notebook in an automated loop.

“The typical loop is short: provision a runtime, run the script, then download artifacts and logs that can be replayed as notebooks.”

Quick reference — common commands

  • colab new — create a session (default CPU; add –gpu or –tpu to request accelerators).
  • colab exec — run Python from stdin, a .py file or a notebook; local files are shipped to the runtime.
  • colab stop — terminate and release the VM.
  • colab upload / colab download — move files to/from the remote runtime.
  • colab log — export session history as .ipynb, .md, .txt or .jsonl for reproducible records.
  • colab repl / colab console — interactive VM shell or Python REPL (interactive use requires a TTY).
  • colab install — add packages (uses uv, falls back to pip).
  • colab drivemount — mount Google Drive to /content/drive.
  • colab auth — authenticate the VM for Google Cloud services (OAuth2).

How it fits into your workflow

Think of Colab CLI as a remote control for ephemeral GPU/TPU machines. The typical scriptable lifecycle: provision the runtime, ship local code and data, run training or evaluation, export logs (replayable as notebooks), download artifacts, and tear down the VM.

colab new --gpu --type=A100
colab exec train.py
colab log --format=ipynb -o session.ipynb
colab download outputs/model_adapter.pt
colab stop

That sequence is CI-friendly and repeatable. The CLI stores session metadata locally (for example at ~/.config/colab-cli/sessions.json), which helps scripts track ephemeral runs and prevents accidental orphaned VMs.

Example: QLoRA fine-tune (short walkthrough)

To demonstrate agent-driven small-model tuning, Google shipped an example where an agent fine-tunes google/gemma-3-1b-it using QLoRA (quantized low-rank adapters). A condensed manual equivalent looks like this:

colab new --gpu --type=A100
colab exec "pip install transformers datasets peft bitsandbytes accelerate"
colab upload train.py
colab exec python train.py --model google/gemma-3-1b-it --method qlora
colab log --format=ipynb -o fine_tune.ipynb
colab download output/adapter.pt
colab stop

Packages used in the example include transformers, datasets, peft, trl, bitsandbytes and accelerate. The CLI ships logs and a replayable notebook, so experiments remain auditable and reproducible — ideal when multiple engineers need to re-run or inspect a run.

Agent integration — what “agent” means and how it works

An agent here means a program that can invoke terminal commands (for example Claude Code, OpenAI Codex-powered tools, or other automation services). The Colab CLI includes a COLAB_SKILL.md which describes how terminal-capable agents should sequence commands, parse outputs and handle artifacts.

Typical agent-driven flow:

  • Agent authenticates (OAuth) and runs colab new to provision an accelerator.
  • Agent installs dependencies, uploads data or scripts, and runs training via colab exec.
  • Agent exports logs via colab log and downloads artifacts via colab download.
  • Agent tears down the runtime with colab stop.

This makes it straightforward to build automated experiment runners, auto-tuning agents, or scheduled CI jobs that need short bursts of GPU/TPU power without maintaining long-lived servers.

Use cases, comparisons and the sweet spot

  • Best fit: prototyping, reproducible experiments, small-model fine-tuning (QLoRA-style), CI test runs and agent-driven automation where cost and speed beat long-term availability.
  • Not a replacement for: production-scale training, long-running jobs, or workloads requiring guaranteed SLAs and predictable cost. For those, provisioned cloud instances or on-prem GPU clusters remain appropriate.
  • Compared to alternatives: local GPUs are faster for iterative debugging with large data, managed cloud VMs give predictable capacity and networking, while Colab CLI offers the lowest friction for ad-hoc, scriptable GPU bursts tied to your terminal or automation agents.

Security & governance checklist

Allowing agents to control Colab sessions accelerates productivity — but add guardrails:

  • Limit OAuth scopes and use service accounts with least privilege where possible.
  • Rotate tokens and avoid embedding credentials in long-lived agent code.
  • Isolate agent execution to dedicated CI runners or sandboxed service accounts.
  • Audit colab log exports centrally and capture artifact provenance (model checkpoints, dataset versions).
  • Restrict Drive mounts to read-only where applicable and avoid mounting sensitive folders.

When to use it — and when to choose something else

Use Colab CLI when you need low-friction GPU/TPU bursts from the terminal, want replayable notebooks for auditability, or are experimenting with agent-driven automation. Avoid it for predictable, mission-critical workloads that require sustained throughput, guaranteed availability, or strict data residency controls.

Key takeaways — quick Q&A

  • How do I run Colab compute from my terminal?

    Install the Colab CLI from the googlecolab/google-colab-cli repo, then use colab new to provision a runtime and colab exec to run code or ship files to the remote VM.

  • Which accelerators can I request via the CLI?

    You can request GPUs like T4, L4, A100 and H100, and TPUs such as v5e1 and v6e1, though availability depends on your Colab plan and quotas.

  • Can AI agents drive Colab runs programmatically?

    Yes — terminal-capable agents can invoke the CLI. The bundled COLAB_SKILL.md provides the context agents need to orchestrate end-to-end runs.

  • How do I retrieve logs and artifacts reproducibly?

    Use colab log to export session history as replayable .ipynb/.md/.txt/.jsonl files, and colab download to fetch artifacts from the runtime.

  • What governance risks should teams mitigate?

    Treat agent access and OAuth credentials like any production secret: limit scopes, rotate keys, centralize logs, and isolate agent runtimes.

Next steps & resources

Try the demo and read the skill file on GitHub: googlecolab/google-colab-cli and COLAB_SKILL.md. Review Colab documentation and quotas at colab.research.google.com. If you want to explore the Gemma example, the model card is available on Hugging Face: google/gemma-3-1b-it.

Want to automate a small-model tuning pipeline or add Colab-powered smoke tests to CI? Start with a few scripted runs, capture session logs via colab log, and build a narrow governance policy for any agents that will orchestrate those runs. Then scale your automation patterns outward.

Architecture suggestion for visuals: a simple diagram — terminal → Colab CLI → Colab runtime (GPU/TPU) → artifact download and replayable logs — clarifies the flow. Alt text example: “Architecture: terminal invoking Colab CLI to provision a Colab GPU runtime and retrieve artifacts.”

Try the CLI, share your agent scripts, and contribute improvements on GitHub — it’s a pragmatic tool to accelerate prototyping and CI-friendly ML workflows, provided you add the right guardrails.

0