# Colab CLI puts a Google Colab runtime behind a terminal

> google-colab-cli is a Python command line client for Google Colab that provisions CPU, GPU and TPU runtimes, executes local scripts and notebooks on them, and manages remote files, with an ephemeral job runner for CI and an SSH mode for remote development. It is Linux and macOS only, and the accelerator and entitlement rules are inherited from the Colab backend rather than from the tool.

**googlecolab/google-colab-cli** — A CLI for interacting with Google Colab runtimes

- Repository: https://github.com/googlecolab/google-colab-cli
- Stars: 1,680 · Forks: 256
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/googlecolab-google-colab-cli

## A browser tab is not a runtime API

Installation is a single package, installed with `uv` where possible or with pip.

```bash
# Using uv (recommended)
uv tool install google-colab-cli

# Using pip
pip install google-colab-cli
```

Google Colab is a hosted notebook environment with real accelerators behind it, and for a long time the only way to reach one was through a browser. The Colab CLI is an attempt to remove the browser from the loop.

The project describes it as a command line interface for Google Colab that provisions high-performance CPU, GPU and TPU runtimes, executes local code, manages remote files and orchestrates automated cloud pipelines, directly from the terminal. The stated design goals are developer productivity, headless automation and AI agent integrations, and all three are visible in the command set rather than being marketing language.

The package is `google-colab-cli` on PyPI, it requires Python 3.12 or newer, and the console script is `colab`, mapped to `colab_cli.cli:main`. The licence is Apache-2.0.

There is one platform constraint stated up front and it is a hard one. The CLI currently supports Linux and macOS only, and Windows is not supported at this time. A team with a mixed developer population therefore has a split toolchain, which is a real cost for something intended to sit in everyone's workflow.

The README also points at a sibling project for the other half of the story. If you are looking for in-notebook, interactive agent-assisted coding instead of a terminal workflow, the Colab MCP Server is the project for that. The split tells you the design intent clearly, this tool is for a terminal, and it is built for automation rather than for a person reading a notebook.

## colab run is the command that matters for automation

The command index is organised by task, and one of the entries stands out as the one built for pipelines.

`colab run` is the ephemeral job runner. It provisions a fresh VM, executes a local script with forwarded arguments, retrieves output files, and tears the runtime down again, all in a single command. The flag set is `colab run [--gpu GPU] [--tpu TPU] [--high-mem] [--keep] SCRIPT [ARGS...]`, where the script and its arguments come last so that the arguments belong to the script rather than to the CLI.

That is a well designed interface for a CI job. There is no session to name, no cleanup step that can be forgotten, and the runtime is destroyed when the command finishes. The `--keep` flag is there for the case where you want the session to survive, which is the escape hatch rather than the default.

The rest of the execution commands are the interactive counterparts. `colab exec` runs code from stdin, a local `.py` file or a `.ipynb` notebook, and takes an `--output-image PATH` option. `colab repl` starts an interactive Python REPL on the VM and exits cleanly on a piped EOF, and `colab console` connects to a raw interactive TTY shell using tmux on the remote VM. `colab ssh` opens an SSH shell over a WebSocket, or acts as an OpenSSH `ProxyCommand` bridge for IDE remote development.

That last one is worth calling out. A ProxyCommand bridge means an IDE that speaks SSH can treat the Colab runtime as a remote machine, so a developer can use their editor's remote development features against a GPU in Google's data centre. That is the feature that makes the CLI usable for day-to-day work rather than only for batch jobs.

## Sessions, files and the archives you can export

The session management commands are the state layer. `colab new` allocates a new CPU, GPU or TPU VM runtime, with an optional `-s NAME` and the accelerator flags, and `--high-mem` for a high-RAM machine shape. `colab sessions` lists all active sessions currently active on the backend, and `colab status` displays the hardware, machine shape, status and local metadata for active sessions. `colab restart-kernel` restarts the active session's Jupyter kernel, `colab stop` terminates a session VM and releases its resources, and `colab url` prints or opens a browser URL connecting to the active session.

The file commands are the ones that make a runtime feel like a filesystem. `colab ls` lists remote files, `colab upload` and `colab download` move files in each direction, `colab rm` deletes one, and `colab edit` edits a remote file in place using your local `$EDITOR`, which is a neat trick because it means a remote file can be changed with a familiar tool.

The automation and utility group is where the archival and accounting features live. `colab auth` authenticates the VM for GCP services such as BigQuery and GCS, `colab drivemount` mounts Google Drive on the VM at `/content/drive` by default, and `colab install` installs packages on the VM using `uv`, falling back to `pip`. `colab log` views or exports session history in `.ipynb`, `.md`, `.txt` or `.jsonl` form. `colab usage` shows the account compute-unit usage rate and balance, `colab pay` opens the Colab subscription page to manage compute units, `colab version` prints the installed version, and `colab update` checks for a newer release and can upgrade in place with `--install`.

The log export is the feature that makes a run reproducible after the fact. A session's history can be written out as a notebook, a Markdown document or JSONL, and in the notebook workflow the outputs are written back into a notebook file such as `report_output.ipynb`.

## Authentication defaults to ADC with OAuth2 as the alternative

The global options are few, and one of them decides how the tool talks to Google.

`--auth {oauth2,adc}` selects the authentication strategy for the Colab API, and the default is `adc`, which is application default credentials. The other option is `oauth2`, which is the path for a user who needs to authenticate interactively. The default is a reasonable choice for a tool that is meant to run in CI, where a service account and a workload identity are how you authenticate anyway.

Two paths complete the configuration. `-c, --client-oauth-config PATH` points at public OAuth client credentials, defaulting to `~/.colab-cli-oauth-config.json`, and that is the file the OAuth2 strategy reads. `--config PATH` sets where local session metadata is stored, defaulting to `~/.config/colab-cli/sessions.json`, which is the file that lets the CLI remember which session is which and what its local metadata is.

There is also `--logtostderr`, which sends debug logging output to stderr rather than wherever it would otherwise go. In a tool that also writes machine output, separating the diagnostic stream from the data stream is the kind of detail that decides whether a command can be used in a pipeline.

One small piece of friction worth knowing: the session option is optional when only one session is active, in which case the CLI automatically knows which one you mean. The documentation makes a point of this, because it is the difference between a one line command and a script full of session names for the common case of a single runtime.

## Liveness, TTY and the entitlement rules behind the flags

Three usage notes in the README describe the boundaries of the tool, and each of them is a different kind of constraint.

The first is liveness. The feature list calls it activity-based liveness, and the explanation is that sessions stay alive as long as the kernel is active, with the Colab backend automatically maintaining liveness. So a runtime is not kept alive by the CLI holding a connection open, it is kept alive by the kernel doing work, and the CLI is a client of that state rather than the reason it exists.

The second is the TTY requirement. The interactive commands `repl` and `console` require a local TTY, and when running inside automated scripts or pipelines you should make sure to pipe stdin, for example `echo "print(1)" | colab repl`, to trigger the non-interactive execution modes. A command that needs a terminal is a command that cannot run unattended unless you give it a pipe, and the documentation is clear that this is on the caller.

The third is the machine shape rules, and these come from the account rather than from the tool. The `--high-mem` flag works with `colab new`, `colab run` or `colab ssh` when auto-creating a runtime, and it requires a Colab Pro or Pro+ entitlement for the supported accelerators, which the note lists as CPU, T4 and A100 among others. L4 and TPU runtimes ignore the flag, because they only offer one shape. The machine shape is shown in `colab sessions` and `colab status`.

So the accelerators on offer are specific. The GPU list is T4, L4, G4, H100 and A100, and the TPU list is v5e1 and v6e1. A request for something else is a request the backend will refuse, and the CLI cannot change that.

## Packaging details worth knowing before you install

The `pyproject.toml` is short and conventional, with two details that matter if you are going to build or vendor it.

The version is dynamic, taken from the version control system. The project metadata declares `dynamic = ["version"]`, the build backend is hatchling with the hatch-vcs plugin, and the version source is configured as `vcs`. There is no version string in the file to bump by hand.

The second detail is a pin with an explanation, and it is the kind of comment worth reading before touching the build. The wheel target sets `core-metadata-version = "2.4"`, and the comment says that hatchling 1.32.0 defaults to 2.5, which the publishing pipeline rejects with the message that 2.5 is not a valid metadata version, silently failing the release, and that the pin should be dropped once 2.5 is accepted. A silent release failure is exactly the kind of thing that is worth a comment, and this one is also a small lesson in what a lock on the publishing side can look like.

The dependency list is worth a glance for the shape of the thing. `typer` and `click` for the command line, `rich` for terminal output, `prompt-toolkit` for the interactive REPL, `pydantic` for the data models, `requests` and `websocket-client` for the transport, `google-auth` and `google-auth-oauthlib` for the two authentication strategies, `jupyter-kernel-client` pinned to exactly 0.9.0, and `nbformat` for notebooks. `filelock` and `html2text` and `pygments` round it out, the last two for rendering output.

The repository itself is a modern Python layout, with `src/` for the package, `tests/` and `integration/` for the two kinds of test, `docs/`, an `examples/` directory with a `finetune_run.py`, a `skills/` directory, a `cloudbuild.yaml` and a `.pre-commit-config.yaml`. The version is dynamic and the metadata is pinned, which is a project that intends to be installed by machines as much as by people.

## Conclusion

The Colab CLI suits a team that wants to run a training job or a notebook on a Colab accelerator as a step in a script, rather than through the browser, and it suits an agent that needs a shell on a remote GPU. It is the wrong tool on Windows, and the wrong tool for interactive notebook work, which is what the companion MCP server is for. Check first that your account has the compute units and the Pro or Pro+ entitlement the machine shape you want requires, because the CLI will happily request a configuration the backend will refuse.

## FAQ

### How do I install the Colab CLI?

With `uv tool install google-colab-cli`, which the project recommends, or with `pip install google-colab-cli`. The package requires Python 3.12 or newer and installs a `colab` console script.

### Does the Colab CLI work on Windows?

No. The README states that the Colab CLI currently supports Linux and macOS only, and that Windows is not supported at this time.

### What is the difference between `colab exec` and `colab run`?

`colab exec` runs code from stdin, a local `.py` file or a `.ipynb` notebook against an existing session. `colab run` is the ephemeral job runner, provisioning a fresh VM, running a local script with forwarded arguments, collecting the output files and tearing the runtime down in one command.

### Which GPUs and TPUs can I request?

The feature list names GPU types T4, L4, G4, H100 and A100, and TPU types v5e1 and v6e1. The `--high-mem` flag needs a Colab Pro or Pro+ entitlement for the supported accelerators, and L4 and TPU runtimes ignore that flag because they only offer one machine shape.

## Sources

- [googlecolab/google-colab-cli on GitHub](https://github.com/googlecolab/google-colab-cli)
- [Issues](https://github.com/googlecolab/google-colab-cli/issues)
- [License: Apache-2.0](https://github.com/googlecolab/google-colab-cli/blob/main/LICENSE)
- [README](https://github.com/googlecolab/google-colab-cli/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/googlecolab-google-colab-cli