gem-hunter

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.

• Instant VM Provisioning: Spin up CPU, GPU (T4, L4, G4, H100, A100), or TPU (v5e1, v6e1) runtimes in seconds.
• Robust Code Execution: Run local Python scripts, Jupyter Notebooks (.ipynb), or piped stdin code; launch interactive REPLs or raw TTY console shells.
• 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.
• Activity-Based Liveness: Sessions stay alive as long as the kernel is active, with the Colab backend automatically maintaining liveness.
• Seamless Workspace Automation: Mount Google Drive, authenticate Google Cloud Platform (GCP) credentials, and install dependencies with high-performance uv package management.
• State & Log Archival: Inspect local session states or export interactive history logs to standard Jupyter Notebooks, Markdown, or structured JSONL.

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

Run colab <command> --help to view specific options, defaults, and detailed help.

• --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 trainer

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:

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

• 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.
• 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.
• 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.
• 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.

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.py

To 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:

• Session Management Architecture
• Interactive & Non-Interactive Execution Design
• File Management & Jupyter Contents API
• Authentication Providers & VM Automation
• Ephemeral Job Runner Design

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.