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.

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 newstarts a CPU, GPU (T4, L4, G4, H100, A100) or TPU (v5e1, v6e1) machine;--high-memasks for a high-RAM shape. - Running code:
colab execruns a.pyscript, an.ipynbnotebook or code from stdin; variables and imports persist between runs in the same session. - One-off jobs:
colab run train.pystarts 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 sshopens 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-operatorskill (colab skillprints it) that tells an agent how to authenticate, run jobs and shut machines down. - Cost:
colab usageshows 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 runruns 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 stopwhen you are done;colab runwithout--keepshuts 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
gcloudfor agents, because the default OAuth flow needs a person to click in a browser. - The script or notebook to run, with its
requirements.txtand 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
- Install the CLI with
uv tool install google-colab-cli, pinning the version. - Authenticate with ADC using
gcloud auth application-default loginwith the four scopes listed in the README. - Try a CPU machine:
colab new -s trial, run one line of code, thencolab stop -s trial. - Run the real job with
colab runon the GPU you need, so the machine shuts down when it finishes. - Install the
colab-operatorskill for your AI agent, and isolate state with--configwhen jobs run in parallel. - Check
colab usageafter each run against your estimate.
Common pitfalls
- Forgetting to stop a machine. A forgotten machine keeps spending compute units;
colab sessionslists 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 drivemountandcolab sshwithout a command hang waiting, or start a billable machine. - Putting untrusted data in
!or%%bashlines. IPython expands{...}and$namethere; pass values through--envas the skill describes. - Confusing
colab authwith CLI login.colab authgives 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 sessionsshows no sessions once the work is done.- Output files are on your machine or in Drive.
colab runexits 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
- google-colab-cli, GitHub
- google-colab-cli on PyPI, PyPI
- Colab Frequently Asked Questions, Google
- colab-mcp, GitHub