gem-hunter
Language: Python
A CLI for interacting with Google Colab runtimes
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.
Designed to support seamless developer productivity, headless automation, and AI agent integrations.
demo.movNote
Platform support: the Colab CLI currently supports Linux and macOS only. Windows is not supported at this time.
Tip
Looking for in-notebook, interactive agent-assisted coding instead of a terminal workflow? See the Colab MCP Server.
.ipynb), or piped stdin code; launch interactive REPLs or raw TTY console shells.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.uv package management.Install the package using uv (recommended) or standard pip:
# Using uv (recommended) uv tool install google-colab-cli # Using pip pip install google-colab-cli
Run a CPU-based VM runtime, execute some code, and clean up:
# 1. Provision a new session colab new # 2. Execute code from stdin echo 'print("Hello from Google Colab!")' | colab exec # 3. Stop and release the VM resource colab stop
Note
When only one session is active, you can omit the -s, --session option;
the CLI automatically knows it.
Run colab <command> --help to view specific options, defaults, and detailed help.
| Command | Description |
|---|---|
colab new [-s NAME] [--gpu GPU] [--tpu TPU] [--high-mem] |
Allocate a new CPU, GPU, or TPU VM runtime (optionally high-RAM) |
colab sessions |
List all active sessions currently active on the backend |
colab status [-s NAME] |
Display hardware, machine shape, status, and local metadata for active sessions |
colab restart-kernel [-s NAME] |
Restart the active session's Jupyter kernel |
colab stop [-s NAME] |
Terminate a session VM and release its resources |
colab url [-s NAME] [--open] |
Print or open a browser URL connecting to the active session |
| Command | Description |
|---|---|
colab run [--gpu GPU] [--tpu TPU] [--high-mem] [--keep] SCRIPT [ARGS...] |
Run a local script on a fresh VM, forwarding arguments, then release it |
colab exec [-s NAME] [-f FILE] [--output-image PATH] |
Execute Python code from stdin, a local .py file, or a .ipynb notebook |
colab repl [-s NAME] [--output-image PATH] |
Start an interactive Python REPL on the VM (exits cleanly on piped EOF) |
colab console [-s NAME] |
Connect to a raw interactive TTY shell (tmux) on the remote VM |
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 |
| Command | Description |
|---|---|
colab ls [-s NAME] [PATH] |
List remote files on the VM |
colab upload [-s NAME] LOCAL REMOTE |
Upload a local file to the VM filesystem |
colab download [-s NAME] REMOTE LOCAL |
Download a remote file from the VM filesystem |
colab rm [-s NAME] PATH |
Delete a remote file on the VM filesystem |
colab edit [-s NAME] PATH |
Edit a remote file in-place using your local $EDITOR |
| Command | Description |
|---|---|
colab auth [-s NAME] |
Authenticate the VM for GCP services (BigQuery, GCS, etc.) |
colab drivemount [-s NAME] [PATH] |
Mount Google Drive on the VM (default: /content/drive) |
colab install [-s NAME] [-r FILE | PKG...] |
Install packages on the VM using uv (falls back to pip) |
colab log [-s NAME] [-n N] [-o FILE] |
View or export session history (.ipynb, .md, .txt, .jsonl) |
colab usage |
Show account compute-unit usage rate and balance |
colab pay |
Open the Colab subscription page to manage compute units |
colab version |
Print the installed version of the CLI |
colab update [--install] |
Check for a newer release (and optionally upgrade the CLI in place) |
--auth {oauth2,adc} — Authentication strategy for the Colab API (default: adc).-c, --client-oauth-config PATH — Path to public OAuth client credentials configuration (default: ~/.colab-cli-oauth-config.json).--config PATH — Path to local session metadata storage (default: ~/.config/colab-cli/sessions.json).--logtostderr — Direct debug logging output to stderr.Provision an A100 GPU, install requirements, run a local training script, retrieve the resulting model weights, and terminate the VM:
colab new -s trainer --gpu A100
colab install -s trainer torch transformers
colab exec -s trainer -f train.py
colab download -s trainer checkpoints/model.bin ./model.bin
colab stop -s trainerMount 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:
colab new -s analysis
colab drivemount -s analysis
colab exec -s analysis -f report.ipynb
colab log -s analysis -o execution_log.md
colab stop -s analysis--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.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.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.~/.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.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:
# Run train.py on a T4 GPU and release the VM on completion
colab run --gpu T4 train.pyTo execute a local file directly on a remote accelerator, place the colab run interpreter in the shebang line:
#!/usr/bin/env -S colab run --gpu L4 --keep import torch print("L4 GPU Available:", torch.cuda.is_available()) print("Device Name:", torch.cuda.get_device_name(0))
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.
For comprehensive architectural overviews and deep-dives into specific CLI sub-systems, refer to the detailed documentation:
To view interactive walkthroughs of eleven real-world automated scenarios, check out the Demo Walkthroughs.
Feedback and contributions are welcome! Please read CONTRIBUTING.md for details.
See Colab's Terms of Service and the Google Privacy Policy, which apply to usage of this CLI.