Engineering & AI

Google Colab CLI: rent Colab GPUs and run code from the terminal, AI agents included

Google Colab CLI runs scripts on Colab GPUs from the terminal so you can automate runs and retrieve results without opening a notebook.

Summary

  • Try one GPU job from the terminal, then verify its output, session status, and compute usage.
  • colab run starts a machine, runs a script and shuts the machine down, which suits AI agents and one-off jobs.
  • A running machine spends compute units; the free tier limits GPUs and may end SSH sessions when your compute unit balance is zero.
Google Colab CLI: rent Colab GPUs and run code from the terminal, AI agents included

You have a script that needs a GPU, but every run means opening Colab, running a notebook, and downloading the results by hand. Google Colab CLI lets you run the same job from your terminal, then verify the output, session status, and compute usage.

Based on the documentation and source code, version 0.8.0 on PyPI (10 November 2026), reviewed on 19 November 2026; we have not run it. HubCom has not used this tool in a client project.

When running a notebook by hand becomes repetitive

  • Colab was a browser tool. To run code on a Colab GPU, you opened a notebook, pasted code, clicked run and downloaded results by hand.
  • CI and agents need a repeatable command. Manual steps make it harder to schedule jobs and collect the results automatically.
  • The repo brings Colab to the command line: starting a machine, running a script, fetching results and shutting down are all commands, so scripts, CI and AI agents can call them.

What it does

  • Machines: colab new starts a CPU, GPU (T4, L4, G4, H100, A100) or TPU (v5e1, v6e1) machine; --high-mem asks for a high-RAM shape.
  • Running code: colab exec runs a .py script, an .ipynb notebook or code from stdin; variables and imports persist between runs in the same session.
  • One-off jobs: colab run train.py starts a fresh machine, runs the script with its arguments, then shuts the machine down, even if the script fails.
  • Files: upload, download, list, delete and edit files on the Colab machine.
  • Shell and IDE: colab ssh opens a shell, runs one command, or acts as an SSH bridge so an IDE (such as VS Code) works directly on the Colab machine.
  • Utilities: mount Google Drive, give the machine GCP credentials, install packages with uv, and export session history as a notebook or Markdown.
  • For AI agents: the repo ships a colab-operator skill (colab skill prints it) that tells an agent how to authenticate, run jobs and shut machines down.
  • Cost: colab usage shows your compute unit burn rate and balance.

It is a Google Colab project under the Apache-2.0 licence, needs Python 3.12 or later, and runs on Linux and macOS.

When to use it

  • Use it when you need a GPU for a few hours to train, fine-tune or try a model, without buying hardware or setting up a cloud account.
  • Use it when an AI agent needs to run heavy code: the agent writes the script, colab run runs it on a GPU, and the results come back to your machine.
  • Use it to rerun an existing notebook from cron or CI and save the results as files.
  • Don't use it for always-on services or customer-facing APIs. Colab forbids file hosting and web serving on its machines, and caps session length.
  • Don't use it when you must have a specific GPU at a specific time. Colab does not guarantee resources; use Colab Enterprise or GCP for that.

Caveats

  • A running machine spends compute units. Always run colab stop when you are done; colab run without --keep shuts down on its own.
  • The free tier is heavily limited. GPUs are scarce, and with a zero compute unit balance Colab may end SSH sessions, remote desktops or distributed workers without warning.
  • Sessions have a time limit. Usually at most 12 hours; Colab Pro+ runs continuously for up to 24 hours with enough compute units.
  • Running out of compute units drops you to free-tier rules, even on a paid plan.
  • Colab bans some uses on every machine: crypto mining, deepfakes, proxies, torrents, and multiple accounts to dodge limits.
  • No Windows support. The README supports Linux and macOS only.
  • Old logs may hold tokens. The CHANGELOG of 19 November 2026 records a fix that stops tokens being written to the debug log; delete logs written by older versions.
  • It changes fast: more than ten PyPI releases between May and November 2026, a few of them yanked. Pin the version on CI machines.

Trying it out

Before handing it to an AI agent, prepare:

  • A Google account for work use, and a Colab plan that fits if you need good GPUs.
  • The authentication method: ADC through gcloud for agents, because the default OAuth flow needs a person to click in a browser.
  • The script or notebook to run, with its requirements.txt and the path of the output files.
  • The machine type: CPU, T4 or A100, and an estimate of run time.
  • A cost cap: the maximum compute units for one trial.

Run one job and retrieve its output

  1. Install the CLI with uv tool install google-colab-cli, pinning the version.
  2. Authenticate with ADC using gcloud auth application-default login with the four scopes listed in the README.
  3. Try a CPU machine: colab new -s trial, run one line of code, then colab stop -s trial.
  4. Run the real job with colab run on the GPU you need, so the machine shuts down when it finishes.
  5. Install the colab-operator skill for your AI agent, and isolate state with --config when jobs run in parallel.
  6. Check colab usage after each run against your estimate.

Common pitfalls

  • Forgetting to stop a machine. A forgotten machine keeps spending compute units; colab sessions lists even sessions your machine no longer tracks.
  • Mistyping a GPU name. An unknown name falls back to A100, the most expensive option, which then usually fails at the next step.
  • Letting an agent run commands that need a person. colab repl, colab auth, colab drivemount and colab ssh without a command hang waiting, or start a billable machine.
  • Putting untrusted data in ! or %%bash lines. IPython expands {...} and $name there; pass values through --env as the skill describes.
  • Confusing colab auth with CLI login. colab auth gives the Colab machine GCP credentials; it does not fix a CLI 401.
  • Leaving sessions unnamed. Without -s, the session gets a random name and later commands can hit the wrong machine.
  • Keeping results on the Colab machine. The machine is deleted when the session ends; download results or write them to Drive before stopping.

Did the output come back and the session stop?

  • colab sessions shows no sessions once the work is done.
  • Output files are on your machine or in Drive.
  • colab run exits with the right code: a failing script returns non-zero, so CI catches it.
  • Compute units spent match the estimate in colab usage.

Out of scope

Comparing Colab prices with other GPU clouds, Colab Enterprise, and the Colab MCP Server for agents working in a browser notebook. See the project source.

Terms in this article (7)
Google Colab CLI
Google Colab's official command-line tool for starting CPU, GPU and TPU machines, running code and managing files from a terminal.
Google Colab
Google's cloud Jupyter notebook service, with free and paid GPU and TPU machines.
Compute unit
Colab's billing unit; stronger machines running longer spend more.
GPU, TPU
Accelerator chips for training and running AI models; TPUs are Google's own chips.
ADC (Application Default Credentials)
A way to sign in to Google Cloud through gcloud without a browser click each time, suited to scripts and AI agents.
Jupyter notebook
An .ipynb file of code cells, outputs and notes, Colab's standard format.
uv
A Python package manager, faster than pip.

Frequently asked questions

Is Google Colab CLI free?

The CLI is free under the Apache-2.0 licence. Colab machines follow your account's plan: the free tier limits GPUs and run time, and paid plans spend compute units by machine type and uptime.

Can I use Google Colab CLI on Windows?

No. The project's README supports Linux and macOS only.

Can AI agents such as Claude Code use Google Colab CLI?

Yes. The repo ships a colab-operator skill that tells an agent how to start machines, run scripts and shut them down. Agents should authenticate with ADC and use colab run so the machine stops when the job ends.

Sources

Talk with HubCom ↗