Colab

---
name: colab
description: "Run code on Colab GPUs or TPUs and track compute units."
license: MIT
metadata:
  kind: connector
  author: Médéric HURIER (Fmind)
  source: github.com/fmind/dot/tree/main/skills/colab
  created: "2026-09-16"
  updated: "2026-10-05"
---

# Google Colab CLI

Use `colab` to inspect existing sessions or run work on an accelerator the workstation lacks. The official Colab skill documents every command; this skill owns provider selection, session hygiene, and the spend boundary.

## Authentication

Pass the global `--auth adc` or `--auth oauth2` before every subcommand: CLI 0.7.4 defaults to OAuth, so do not rely on implicit defaults or upstream main. ADC reuses credentials from [gcloud](../gcloud/SKILL.md); for user ADC, run `dot login colab`, which requests the configured ADC grant only when it lacks the Colab scopes and verifies session access (`--dry-run` previews the native commands; the [authentication guide](../dot-cli/references/authentication.md#colab-adc) owns its scopes and semantics). Session state lives under `~/.config/colab-cli/`. Examples assume ADC; substitute `oauth2` for an existing OAuth profile.

## Inspect without allocating

Check `colab version` and installed help, then use `colab --auth adc sessions` and `colab --auth adc status`; they synchronize session metadata without allocating or stopping a VM. Check authentication diagnostics before interpreting an empty listing as success.

Use `colab --auth adc usage` for compute-unit rate and balance; if it is unavailable, report a missing capability instead of allocating a VM. `colab pay` opens a purchase page and is not a balance query. Session inspection does not require `new`, `run`, `exec`, or `stop`.

## Run accelerator work

Follow this workflow only when remote execution is in scope; establish the authorized accelerator, duration, and budget before allocation.

1. **Prefer ephemeral runs for self-persisting scripts**: `colab run` rents a VM, runs the script, and attempts to release it. Save needed artifacts to an authorized durable destination before the script exits; local VM files disappear on release. Use an explicitly managed session when artifacts must be downloaded afterwards. A shebang `#!/usr/bin/env -S colab --auth adc run --gpu T4` supports single-file execution per [python-script](../python-stack/references/python-script/GUIDE.md).

   ```bash
   colab --auth adc run --gpu T4 --timeout 3600 train.py
   ```

1. **Keep a session only while iterating**: `colab --auth adc new -s <name> --gpu L4` (or `--tpu v6e1`), then `colab --auth adc exec -s <name> -f snippet.py --timeout 600`. Use `upload`, `download`, `ls`, `status`, and `log` with the same provider; verify and retrieve needed artifacts before stopping.
1. **Stop what you started and verify release**: `colab --auth adc stop -s <name>`, then refresh `colab --auth adc sessions`; an idle session keeps consuming compute units. CLI 0.7.4's ephemeral cleanup suppresses release errors, so a successful `run` exit or “Session terminated” message is not release proof. Check authentication diagnostics and the backend listing before reporting cleanup complete.

## Gotchas

- **Override the 30-second default**: `colab run` and `colab exec` abort code execution after 30 seconds unless `--timeout <seconds>` covers the whole job.
- **Let Colab pick the kernel client**: google-colab-cli 0.7.4 pins `jupyter-kernel-client==0.9.0`; let Colab select its compatible client instead of adding a conflicting mise `with` override.
- **Treat `colab pay` as spend**: accelerator availability depends on the subscription; `colab pay` opens the compute-units page, so treat it as spend.
- **Treat the VM as disposable**: keep secrets off the session beyond what the task needs; use `colab drivemount` only when Drive data is required.

## Official Skills

Upstream: `googlecolab/google-colab-cli`, the same source `colab skill` prints. Follow the shared [vendor-skill policy](../agent-project/references/vendor-skills.md) and select only the Colab workflow needed by the project.

## Documentation

- [Colab CLI](https://github.com/googlecolab/google-colab-cli)
- Releases: [google-colab-cli changelog](https://github.com/googlecolab/google-colab-cli/blob/main/CHANGELOG.md)
- ML workflows: [python-mlops](../python-mlops/SKILL.md) owns data validation, training, experiments, and model delivery.
- Companion skills: [kaggle](../kaggle/SKILL.md), [hf](../hf/SKILL.md), [python-script](../python-stack/references/python-script/GUIDE.md), [gcloud](../gcloud/SKILL.md).