| 1 | # Colab CLI |
| 2 | |
| 3 | A command-line interface for Google Colab. Provision high-performance CPU, GPU, and TPU runtimes, execute local code, manage remote files, and orchestrate automated cloud pipelines — directly from your terminal. |
| 4 | |
| 5 | Designed to support seamless developer productivity, headless automation, and AI agent integrations. |
| 6 | |
| 7 | [Demo](https://github.com/user-attachments/assets/656226a9-af13-4fdb-8eda-d7de747336a2) |
| 8 | |
| 9 | > [!NOTE] |
| 10 | > **Platform support:** the Colab CLI currently supports **Linux and macOS** only. Windows is not supported at this time. |
| 11 | |
| 12 | > [!TIP] |
| 13 | > Looking for in-notebook, interactive agent-assisted coding instead of a terminal workflow? See the [Colab MCP Server](https://github.com/googlecolab/colab-mcp). |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## Key Features |
| 18 | |
| 19 | * **Instant VM Provisioning:** Spin up CPU, GPU (T4, L4, G4, H100, A100), or TPU (v5e1, v6e1) runtimes in seconds. |
| 20 | * **Robust Code Execution:** Run local Python scripts, Jupyter Notebooks (`.ipynb`), or piped `stdin` code; launch interactive REPLs or raw TTY console shells. |
| 21 | * **Ephemeral Job Runner (`colab run`):** Provision a fresh VM, execute a local script with forwarded arguments, retrieve output files, and automatically tear down the runtime in a single command. |
| 22 | * **Automatic Keep-Alive:** Built-in background daemon automatically prevents idle VM termination, keeping resource allocations active without requiring open browser tabs. |
| 23 | * **Seamless Workspace Automation:** Mount Google Drive, authenticate Google Cloud Platform (GCP) credentials, and install dependencies with high-performance `uv` package management. |
| 24 | * **State & Log Archival:** Inspect local session states or export interactive history logs to standard Jupyter Notebooks, Markdown, or structured JSONL. |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## Installation |
| 29 | |
| 30 | Install the package using `uv` (recommended) or standard `pip`: |
| 31 | |
| 32 | ```bash |
| 33 | # Using uv (recommended) |
| 34 | uv tool install google-colab-cli |
| 35 | |
| 36 | # Using pip |
| 37 | pip install google-colab-cli |
| 38 | ``` |
| 39 | |
| 40 | --- |
| 41 | |
| 42 | ## Quick Start |
| 43 | |
| 44 | Run a CPU-based VM runtime, execute some code, and clean up: |
| 45 | |
| 46 | ```bash |
| 47 | # 1. Provision a new session |
| 48 | colab new |
| 49 | |
| 50 | # 2. Execute code from stdin |
| 51 | echo "print('Hello from Google Colab!')" | colab exec |
| 52 | |
| 53 | # 3. Stop and release the VM resource |
| 54 | colab stop |
| 55 | ``` |
| 56 | |
| 57 | > [!NOTE] |
| 58 | > When only one session is active, you can omit the `-s, --session` option; |
| 59 | > the CLI automatically knows it. |
| 60 | |
| 61 | |
| 62 | --- |
| 63 | |
| 64 | ## Command Index |
| 65 | |
| 66 | Run `colab <command> --help` to view specific options, defaults, and detailed help. |
| 67 | |
| 68 | ### Session Management |
| 69 | | Command | Description | |
| 70 | | --- | --- | |
| 71 | | `colab new [-s NAME] [--gpu GPU] [--tpu TPU] [--high-mem]` | Allocate a new CPU, GPU, or TPU VM runtime (optionally high-RAM) | |
| 72 | | `colab sessions` | List all active sessions currently active on the backend | |
| 73 | | `colab status [-s NAME]` | Display hardware, machine shape, status, and local metadata for active sessions | |
| 74 | | `colab restart-kernel [-s NAME]` | Restart the active session's Jupyter kernel | |
| 75 | | `colab stop [-s NAME]` | Terminate a session VM and tear down its keep-alive daemon | |
| 76 | | `colab url [-s NAME] [--open]` | Print or open a browser URL connecting to the active session | |
| 77 | |
| 78 | ### Execution |
| 79 | | Command | Description | |
| 80 | | --- | --- | |
| 81 | | `colab run [--gpu GPU] [--tpu TPU] [--high-mem] [--keep] SCRIPT [ARGS...]` | Run a local script on a fresh VM, forwarding arguments, then release it | |
| 82 | | `colab exec [-s NAME] [-f FILE] [--output-image PATH]` | Execute Python code from stdin, a local `.py` file, or a `.ipynb` notebook | |
| 83 | | `colab repl [-s NAME] [--output-image PATH]` | Start an interactive Python REPL on the VM (exits cleanly on piped EOF) | |
| 84 | | `colab console [-s NAME]` | Connect to a raw interactive TTY shell (tmux) on the remote VM | |
| 85 | | `colab ssh [-s NAME] [--proxy-mode] [-i KEY] [--gpu GPU] [--tpu TPU] [--high-mem]` | Open an SSH shell to the runtime over WebSocket, or act as an OpenSSH `ProxyCommand` bridge for IDE remote-dev | |
| 86 | |
| 87 | ### File Operations |
| 88 | | Command | Description | |
| 89 | | --- | --- | |
| 90 | | `colab ls [-s NAME] [PATH]` | List remote files on the VM | |
| 91 | | `colab upload [-s NAME] LOCAL REMOTE` | Upload a local file to the VM filesystem | |
| 92 | | `colab download [-s NAME] REMOTE LOCAL` | Download a remote file from the VM filesystem | |
| 93 | | `colab rm [-s NAME] PATH` | Delete a remote file on the VM filesystem | |
| 94 | | `colab edit [-s NAME] PATH` | Edit a remote file in-place using your local `$EDITOR` | |
| 95 | |
| 96 | ### Automation & Utilities |
| 97 | | Command | Description | |
| 98 | | --- | --- | |
| 99 | | `colab auth [-s NAME]` | Authenticate the VM for GCP services (BigQuery, GCS, etc.) | |
| 100 | | `colab drivemount [-s NAME] [PATH]` | Mount Google Drive on the VM (default: `/content/drive`) | |
| 101 | | `colab install [-s NAME] [-r FILE \| PKG...]` | Install packages on the VM using `uv` (falls back to `pip`) | |
| 102 | | `colab log [-s NAME] [-n N] [-o FILE]` | View or export session history (`.ipynb`, `.md`, `.txt`, `.jsonl`) | |
| 103 | | `colab pay` | Open the Colab subscription page to manage compute units | |
| 104 | | `colab version` | Print the installed version of the CLI | |
| 105 | | `colab update [--install]` | Check for a newer release (and optionally upgrade the CLI in place) | |
| 106 | |
| 107 | ### Global Options |
| 108 | * `--auth {oauth2,adc}` — Authentication strategy for the Colab API (default: `adc`). |
| 109 | * `-c, --client-oauth-config PATH` — Path to public OAuth client credentials configuration (default: `~/.colab-cli-oauth-config.json`). |
| 110 | * `--config PATH` — Path to local session metadata storage (default: `~/.config/colab-cli/sessions.json`). |
| 111 | * `--logtostderr` — Direct debug logging output to stderr. |
| 112 | |
| 113 | --- |
| 114 | |
| 115 | ## Practical Examples |
| 116 | |
| 117 | ### Accelerator Training with Checkpoint Retrieval |
| 118 | |
| 119 | Provision an A100 GPU, install requirements, run a local training script, retrieve the resulting model weights, and terminate the VM: |
| 120 | |
| 121 | ```bash |
| 122 | colab new -s trainer --gpu A100 |
| 123 | colab install -s trainer torch transformers |
| 124 | colab exec -s trainer -f train.py |
| 125 | colab download -s trainer checkpoints/model.bin ./model.bin |
| 126 | colab stop -s trainer |
| 127 | ``` |
| 128 | |
| 129 | ### Workspace Notebook Execution with Drive Integration |
| 130 | |
| 131 | Mount Google Drive, run a local notebook against the VM kernel (outputs are written back into `report_output.ipynb`), export a Markdown log of the execution, and clean up: |
| 132 | |
| 133 | ```bash |
| 134 | colab new -s analysis |
| 135 | colab drivemount -s analysis |
| 136 | colab exec -s analysis -f report.ipynb |
| 137 | colab log -s analysis -o execution_log.md |
| 138 | colab stop -s analysis |
| 139 | ``` |
| 140 | |
| 141 | --- |
| 142 | |
| 143 | ## Usage Notes |
| 144 | |
| 145 | * **Machine shape:** Use `--high-mem` with `colab new`, `colab run`, or `colab ssh` (when auto-creating a runtime) to request a high-RAM machine shape. Requires Colab Pro or Pro+ entitlement for supported accelerators (CPU, T4, A100, etc.). L4 and TPU runtimes ignore this flag because they only offer one shape. Machine shape is shown in `colab sessions` and `colab status`. |
| 146 | * **TTY Requirements:** The interactive commands `repl` and `console` require a local TTY. When running inside automated scripts or pipelines, make sure to pipe stdin (e.g., `echo "print(1)" | colab repl`) to trigger non-interactive execution modes. |
| 147 | * **Transparent Code Execution:** When calling `colab exec -f file.py`, the CLI reads the file locally and transmits its content to the remote kernel. You do not need to manually upload files before execution. |
| 148 | * **Storage & State Paths:** Session tokens and metadata are stored at `~/.config/colab-cli/sessions.json`. Global CLI settings are located at `~/.config/colab-cli/settings.json`. These can be customized or isolated via the global `--config` flag. |
| 149 | |
| 150 | ### Ephemeral Accelerator Jobs |
| 151 | |
| 152 | Use `colab run` to run a local script on dedicated hardware without manual session lifecycle management. The CLI handles provisioning, script execution, and immediate VM teardown automatically: |
| 153 | |
| 154 | ```bash |
| 155 | # Run train.py on a T4 GPU and release the VM on completion |
| 156 | colab run --gpu T4 train.py |
| 157 | ``` |
| 158 | |
| 159 | ### Shebang Execution Support |
| 160 | |
| 161 | To execute a local file directly on a remote accelerator, place the `colab run` interpreter in the shebang line: |
| 162 | |
| 163 | ```python |
| 164 | #!/usr/bin/env -S colab run --gpu L4 --keep |
| 165 | import torch |
| 166 | |
| 167 | print("L4 GPU Available:", torch.cuda.is_available()) |
| 168 | print("Device Name:", torch.cuda.get_device_name(0)) |
| 169 | ``` |
| 170 | |
| 171 | Make the script executable (`chmod +x script.py`) and run it: `./script.py`. The `--keep` option tells the CLI to preserve the session VM on completion so you can re-execute or inspect logs. |
| 172 | |
| 173 | --- |
| 174 | |
| 175 | ## Deep Dive Documentation |
| 176 | |
| 177 | For comprehensive architectural overviews and deep-dives into specific CLI sub-systems, refer to the detailed documentation: |
| 178 | |
| 179 | * [Session Management & Keep-Alive Architecture](docs/01_session_management.md) |
| 180 | * [Interactive & Non-Interactive Execution Design](docs/02_execution_and_interactive.md) |
| 181 | * [File Management & Jupyter Contents API](docs/03_file_management.md) |
| 182 | * [Authentication Providers & VM Automation](docs/04_automation_and_utility.md) |
| 183 | * [Ephemeral Job Runner Design](docs/05_run_command.md) |
| 184 | |
| 185 | To view interactive walkthroughs of eleven real-world automated scenarios, check out the [Demo Walkthroughs](docs/demos.md). |
| 186 | |
| 187 | --- |
| 188 | |
| 189 | ## Contributing |
| 190 | |
| 191 | Feedback and contributions are welcome! Please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details. |