colab

colab [global-options] command [options] [args...]

colab is the official command-line client for Google Colab. The installed binary is `colab` (PyPI package `google-colab-cli`). It provisions CPU, GPU, and TPU VMs, runs local Python and notebooks on those kernels, copies files, and can open a REPL, tmux console, or SSH session, all from a Linux or macOS terminal.A session is a named assignment stored locally in `sessions.json` and on Colab's backend. When exactly one session is active, -s / --session can be omitted. `colab exec -f` reads the file on the client and sends the source to the kernel; the working directory on the VM is `/content`. Sessions stay assigned while the kernel is active; the CLI pings the tunnel frontend keep-alive path rather than requiring a separate local daemon.GPU values accepted by --gpu are T4, L4, G4, H100, and A100. TPU values for --tpu are v5e1 and v6e1. Availability and high-RAM shapes depend on the Colab subscription. Allocation can fail with a 412 (too many assignments or a capacity limit) or a 400 (no entitlement for that accelerator).

-h, --help

Show help. `colab help` [command] prints the same text for one subcommand.

How the CLI authenticates to Colab. Default is oauth2 (copy-paste Installed App flow). adc uses Application Default Credentials (`GOOGLEAPPLICATIONCREDENTIALS`, `gcloud auth application-default login`, or a GCE/GKE metadata server).

OAuth client JSON for --auth oauth2. Default: `~/.colab-cli-oauth-config.json`. The wheel also ships an inlined client used when that file is missing.

Session metadata file. Default: `~/.config/colab-cli/sessions.json`.

Send debug logs to stderr.

Allocate a VM. With neither --gpu nor --tpu, the runtime is CPU. --high-mem requests a high-RAM shape (Colab Pro or Pro+; ignored for L4 and TPU).

List assignments on the backend, with local names, hardware, machine shape, and variant.

Print hardware, shape, IDLE/BUSY, and last-execution metadata for local sessions.

Restart the Jupyter kernel on an existing session.

Shut down the kernel, unassign the VM, and drop local state.

Print a Colab notebook URL that attaches to the existing VM. --open also launches a browser. Default host is `https://colab.research.google.com`.

Execute stdin, a `.py` file, or a `.ipynb` notebook on an existing session. See colab-exec(1).

Allocate a fresh VM, run a local script, then release it unless --keep. See colab-run(1).

Interactive Python REPL on the VM. Piped stdin runs once and exits.

Raw TTY (tmux) on the remote VM. Needs a local TTY.

SSH over WebSocket into `/content`. With no sessions, auto-creates a runtime. --proxy-mode is an OpenSSH `ProxyCommand` bridge. --rm stops an auto-created runtime on exit (and, in proxy mode, the bridged session on disconnect). RSA keys are rejected; Ed25519 or ECDSA only.

List remote files. Default path is `content` (the Jupyter contents API name for `/content`).

Upload a local file to the VM.

Download a remote file.

Delete a remote file.

Download a remote file, open `$EDITOR`, upload if it changed. A missing remote file starts empty.

Mount Google Drive. Default path: `/content/drive`. May prompt for a browser authorization URL.

Install packages on the VM with `uv pip install --system`, falling back to `pip`. A --requirement file is uploaded first.

Run `google.colab.auth.authenticate_user()` on the VM (hidden from `colab --help`).

Show or export local session history. --output suffix selects `.ipynb`, `.md`, `.txt`, or `.jsonl`.

Print compute-unit rate and balance.

Open `https://colab.research.google.com/signup`.

Print the installed CLI version.

Check PyPI for a newer `google-colab-cli`. --install runs `pip install -U google-colab-cli` on Linux and macOS.

~/.config/colab-cli/sessions.json

Local session tokens, endpoints, hardware, and last-execution metadata. Override with --config.

CLI settings, including the cached latest-version banner used by update.

Cached OAuth2 user token for --auth oauth2.

Optional public OAuth client JSON. If absent, the packaged `oauth_config.json` is used.

Linux and macOS only. Requires Python 3.12 or later. A Google account and Colab's Terms of Service apply; GPU, TPU, and --high-mem need the matching Colab plan and quota.colab exec and colab run default --timeout to 30 seconds. Long jobs must raise it. An unrecognized --gpu string is mapped to A100, not rejected. --high-mem is ignored for L4 and TPU shapes.repl and console need a local TTY unless stdin is piped. colab ssh does not accept RSA keys. auth is registered but hidden from the default help listing.Default --auth is oauth2, which prints an authorization URL and reads a pasted code (the same remote flow as `gcloud auth application-default login`). README text that names adc as the default does not match the Typer callback.

Google announced the Colab CLI on 5 June 2026. The first PyPI release was 0.5.4 on 22 May 2026. 0.6.0 (16 June 2026) switched OAuth2 to the remote copy-paste flow and replaced a keep-alive RPC that 403'd for external users. 0.7.0 (3 September 2026) added colab ssh, --env, and --high-mem; 0.7.1 (14 September 2026) unblocked that release on PyPI. The package is Apache-2.0 and built with Typer.

colab-exec(1), colab-run(1), jupyter(1), python3(1), pip(1), uv(1), gcloud(1)

Source code · Documentation