google-colab-cli 0.5.7__tar.gz → 0.5.9__tar.gz

google_colab_cli-0.5.9/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: google-colab-cli
+Version: 0.5.9
+Summary: CLI for interacting with Colab.
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: click>=8.0
+Requires-Dist: google-auth-oauthlib>=1.3.0
+Requires-Dist: google-auth>=2.49.1
+Requires-Dist: jupyter-kernel-client
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: packaging>=24.0
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pygments>=2.19.2
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Requires-Dist: typing-extensions>=4.0
+Requires-Dist: websocket-client>=1.0
+Description-Content-Type: text/markdown
+
+# Colab CLI
+
+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.
+
+---
+
+## Key Features
+
+* **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.
+* **Automatic Keep-Alive:** Built-in background daemon automatically prevents idle VM termination, keeping resource allocations active without requiring open browser tabs.
+* **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.
+
+---
+
+## Installation
+
+Install the package using `uv` (recommended) or standard `pip`:
+
+```bash
+# Using uv (recommended)
+uv tool install google-colab-cli
+
+# Using pip
+pip install google-colab-cli
+```
+
+---
+
+## Quick Start
+
+Run a CPU-based VM runtime, execute some code, and clean up:
+
+```bash
+# 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.
+
+
+---
+
+## Command Index
+
+Run `colab <command> --help` to view specific options, defaults, and detailed help.
+
+### Session Management
+| Command | Description |
+| --- | --- |
+| `colab new [-s NAME] [--gpu GPU] [--tpu TPU]` | Allocate a new CPU, GPU, or TPU VM runtime |
+| `colab sessions` | List all active sessions currently active on the backend |
+| `colab status [-s NAME]` | Display hardware, 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 tear down its keep-alive daemon |
+| `colab url [-s NAME] [--open]` | Print or open a browser URL connecting to the active session |
+
+### Execution
+| Command | Description |
+| --- | --- |
+| `colab run [--gpu GPU] [--tpu TPU] [--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 |
+
+### File Operations
+| 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` |
+
+### Automation & Utilities
+| 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 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) |
+
+### Global Options
+* `--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.
+
+---
+
+## Practical Examples
+
+### Accelerator Training with Checkpoint Retrieval
+
+Provision an A100 GPU, install requirements, run a local training script, retrieve the resulting model weights, and terminate the VM:
+
+```bash
+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
+```
+
+### Workspace Notebook Execution with Drive Integration
+
+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:
+
+```bash
+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
+```
+
+---
+
+## Usage Notes
+
+* **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.
+
+### Ephemeral Accelerator Jobs
+
+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:
+
+```bash
+# Run train.py on a T4 GPU and release the VM on completion
+colab run --gpu T4 train.py
+```
+
+### Shebang Execution Support
+
+To execute a local file directly on a remote accelerator, place the `colab run` interpreter in the shebang line:
+
+```python
+#!/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.
+
+---
+
+## Deep Dive Documentation
+
+For comprehensive architectural overviews and deep-dives into specific CLI sub-systems, refer to the detailed documentation:
+
+* [Session Management & Keep-Alive Architecture](docs/01_session_management.md)
+* [Interactive & Non-Interactive Execution Design](docs/02_execution_and_interactive.md)
+* [File Management & Jupyter Contents API](docs/03_file_management.md)
+* [Authentication Providers & VM Automation](docs/04_automation_and_utility.md)
+* [Ephemeral Job Runner Design](docs/05_run_command.md)
+
+To view interactive walkthroughs of eleven real-world automated scenarios, check out the [Demo Walkthroughs](docs/demos.md).
+
+---
+
+## Contributing
+
+Feedback and contributions are welcome! Please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details.

google_colab_cli-0.5.9/README.md

@@ -0,0 +1,181 @@
+# Colab CLI
+
+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.
+
+---
+
+## Key Features
+
+* **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.
+* **Automatic Keep-Alive:** Built-in background daemon automatically prevents idle VM termination, keeping resource allocations active without requiring open browser tabs.
+* **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.
+
+---
+
+## Installation
+
+Install the package using `uv` (recommended) or standard `pip`:
+
+```bash
+# Using uv (recommended)
+uv tool install google-colab-cli
+
+# Using pip
+pip install google-colab-cli
+```
+
+---
+
+## Quick Start
+
+Run a CPU-based VM runtime, execute some code, and clean up:
+
+```bash
+# 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.
+
+
+---
+
+## Command Index
+
+Run `colab <command> --help` to view specific options, defaults, and detailed help.
+
+### Session Management
+| Command | Description |
+| --- | --- |
+| `colab new [-s NAME] [--gpu GPU] [--tpu TPU]` | Allocate a new CPU, GPU, or TPU VM runtime |
+| `colab sessions` | List all active sessions currently active on the backend |
+| `colab status [-s NAME]` | Display hardware, 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 tear down its keep-alive daemon |
+| `colab url [-s NAME] [--open]` | Print or open a browser URL connecting to the active session |
+
+### Execution
+| Command | Description |
+| --- | --- |
+| `colab run [--gpu GPU] [--tpu TPU] [--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 |
+
+### File Operations
+| 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` |
+
+### Automation & Utilities
+| 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 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) |
+
+### Global Options
+* `--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.
+
+---
+
+## Practical Examples
+
+### Accelerator Training with Checkpoint Retrieval
+
+Provision an A100 GPU, install requirements, run a local training script, retrieve the resulting model weights, and terminate the VM:
+
+```bash
+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
+```
+
+### Workspace Notebook Execution with Drive Integration
+
+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:
+
+```bash
+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
+```
+
+---
+
+## Usage Notes
+
+* **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.
+
+### Ephemeral Accelerator Jobs
+
+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:
+
+```bash
+# Run train.py on a T4 GPU and release the VM on completion
+colab run --gpu T4 train.py
+```
+
+### Shebang Execution Support
+
+To execute a local file directly on a remote accelerator, place the `colab run` interpreter in the shebang line:
+
+```python
+#!/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.
+
+---
+
+## Deep Dive Documentation
+
+For comprehensive architectural overviews and deep-dives into specific CLI sub-systems, refer to the detailed documentation:
+
+* [Session Management & Keep-Alive Architecture](docs/01_session_management.md)
+* [Interactive & Non-Interactive Execution Design](docs/02_execution_and_interactive.md)
+* [File Management & Jupyter Contents API](docs/03_file_management.md)
+* [Authentication Providers & VM Automation](docs/04_automation_and_utility.md)
+* [Ephemeral Job Runner Design](docs/05_run_command.md)
+
+To view interactive walkthroughs of eleven real-world automated scenarios, check out the [Demo Walkthroughs](docs/demos.md).
+
+---
+
+## Contributing
+
+Feedback and contributions are welcome! Please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details.

{google_colab_cli-0.5.7 → google_colab_cli-0.5.9}/docs/02_execution_and_interactive.md

@@ -26,6 +26,7 @@ Execution involves sending Python code (or shell commands) to the Jupyter kernel
     - If file path is local: Read content, send as code.
     - If file path is remote: Execute `!python <path>`.
 - **Multi-Modal Output**: Handle `display_data` messages (e.g., `image/png`, `text/html`). For the CLI, we'll save images to temporary files and print their paths, or if the terminal supports it (e.g., iTerm2), inline them.
+- **Timeout Configuration**: Exposes a `--timeout` flag (default 10s) to allow long-running silent tasks (like model compilation or data downloading) to execute without being prematurely killed.
 
 ### 3. Console (`colab console`)
 - **Implementation**: Connects directly to the backend terminal endpoint (`/colab/tty`) via WebSockets using `websocket-client`.

{google_colab_cli-0.5.7 → google_colab_cli-0.5.9}/docs/04_automation_and_utility.md

@@ -1,5 +1,8 @@
 ---
 log:
+2026-06-01: Enabled `colab update --install` self-update on macOS in addition to Linux. Refactored platform check logic to keep the implementation DRY and updated both tests and documentation. Also, on these platforms, an additional message is shown recommending `colab update --install` to upgrade in place, positioned above the standard `pip`/`uv` installation command.
+2026-05-29: Added default OAuth2 client config (`oauth_config.json`) as a bundled package resource and restored fallback loading logic in `get_credentials()`. The CLI now falls back to using these default credentials when no explicit local config is found. Added `integration/repro_bundled_oauth` integration test.
+2026-05-27: Refactored `colab README` and `colab AGENT` to bundle `README.md` and `AGENTS.md` via Hatchling's `force-include` and read them using `importlib.resources` instead of `importlib.metadata`. `colab AGENT` now correctly prints `AGENTS.md`.
 2026-05-27: Extended `colab update --install` to detect if the CLI was installed via `uv tool install` (by checking if `sys.executable` contains `/uv/`) and if so, use `uv tool install -U google-colab-cli` to upgrade.
 2026-05-27: Updated auto-update upgrade hint to recommend `pip install --upgrade google-colab-cli` instead of `colab`, aligning with the PyPI package name.
 2026-05-27: `colab url` now emits BOTH the `?dbu=<urlencoded path>` query parameter (existing) AND a new `#datalabBackendUrl=<full URL>` hash fragment (new). Format: `https://<host>/notebooks/empty.ipynb?dbu=%2Ftun%2Fm%2F<endpoint>#datalabBackendUrl=<host>/tun/m/<endpoint>`. Why both: some Colab frontend code paths consult the hash fragment first and ignore `dbu` entirely, so the previously-emitted query-only form failed silently for those users (the frontend fell through to allocating a fresh VM via `/tun/m/assign`). The fragment value is a FULL URL with scheme + host (NOT just the path) and is emitted RAW (no URL encoding) because browsers don't decode the fragment before passing `location.hash` to page JS — Colab's parser calls `new URL(rawString)` directly. The fragment host always matches `--host` so Colab's same-origin enforcement on embedded backend URLs doesn't block the connection, and sandbox/dev users (`--host https://colab.sandbox.google.com`) get a sandbox fragment automatically. Three new test cases in `tests/test_url.py` cover the raw-encoding requirement (`%3A`/`%2F` must NOT appear in the fragment), the both-signals-present invariant, and `--open` propagating the fragment to `webbrowser.open()`. Integration-verified live against synthetic session state with three host shapes (default, sandbox, trailing-slash); all produced correctly-shaped URLs with no `//` artifacts.
@@ -22,9 +25,9 @@ backend, selected via the global `--auth=<provider>` flag:
 
 1.  **`oauth2`** (default): Standard public InstalledAppFlow via
     `google-auth-oauthlib`. Opens a browser for consent, caches the refresh
-    token at `~/.config/colab-cli/token.json`. Requires a client OAuth
-    config at `~/.colab-cli-oauth-config.json` or a path passed via
-    `-c/--client-oauth-config`.
+    token at `~/.config/colab-cli/token.json`. If no local config is provided
+    via `-c/--client-oauth-config` or found at `~/.colab-cli-oauth-config.json`,
+    it falls back to a bundled `oauth_config.json` containing default OAuth credentials.
 2.  **`adc`**: Application Default Credentials via `google.auth.default()`.
     Honors the standard ADC discovery chain
     (`GOOGLE_APPLICATION_CREDENTIALS`, `gcloud auth application-default
@@ -184,10 +187,12 @@ remediation guidance) rather than silently after ~1 minute via the daemon.
             the cache.
 -   **Notification**: If a new version is found, a non-intrusive message is
     printed to the console with a `Run 'pip install --upgrade google-colab-cli' to
-    update.` hint. The cached banner shown between fetches uses the generic
-    `Run 'colab update' to update.` hint.
+    update.` hint. On Linux and macOS platforms where `--install` self-update is supported,
+    an additional hint `You can run 'colab update --install' to upgrade in place.`
+    is displayed above the pip/uv install command. The cached banner shown between
+    fetches uses the generic `Run 'colab update' to update.` hint.
 -   **Self-install (`--install`)**: An opt-in `--install` flag (default
-    `False`) makes `colab update` upgrade the CLI in place (**Linux only**).
+    `False`) makes `colab update` upgrade the CLI in place (**Linux and macOS**).
     It detects how the CLI was installed:
     - If `sys.executable` contains `/uv/tools` (indicating it was installed via
       `uv tool install`), it runs `uv tool install -U google-colab-cli`.
@@ -241,6 +246,19 @@ remediation guidance) rather than silently after ~1 minute via the daemon.
       - openid
     ```
 
+### 9. README and AGENT (`colab README`, `colab AGENT`)
+
+-   **Action**: Print the bundled `README.md` or `AGENTS.md` file.
+-   **Implementation**:
+    -   Uses `importlib.resources.files("colab_cli").joinpath(...)` to read the
+        bundled `README.md` (for `colab README`) or `AGENTS.md` (for `colab AGENT`)
+        from the package resources.
+    -   The files are bundled into the package via Hatchling's `force-include`
+        configuration in `pyproject.toml`.
+    -   If reading from resources fails (e.g. during development when not
+        installed), it falls back to reading the files from the project root.
+    -   Prints the content to stdout.
+
 ## Implementation Details
 
 -   **Code Injection**: Use a standard `run_code(session, code)` helper via
@@ -286,3 +304,10 @@ TDD is mandatory for all automation features.
 -   **Test Case**: `creds.refresh()` is called before `creds.token` is read
     (regression against silently-`None` tokens for service-account /
     GCE-metadata creds).
+
+### 4. `README` and `AGENT` Commands
+
+-   **Test Case**: Verify `colab README` prints the expected content when package metadata is available.
+-   **Test Case**: Verify `colab AGENT` prints the same content.
+-   **Test Case**: Verify fallback to local `README.md` file when metadata is not available.
+-   **Test Case**: Verify error exit when both metadata and local file are unavailable.

{google_colab_cli-0.5.7 → google_colab_cli-0.5.9}/docs/05_run_command.md

@@ -29,6 +29,7 @@ colab run [OPTIONS] SCRIPT [SCRIPT_ARGS]...
 | `--gpu` | str | None | Same set as `colab new --gpu` (T4, L4, G4, H100, A100). |
 | `--tpu` | str | None | Same set as `colab new --tpu` (v5e1, v6e1). |
 | `--keep` | bool | False | Do **not** stop the session after the script finishes. |
+| `--timeout` | float | 10.0 | Timeout in seconds for code execution to prevent hanging on silent tasks. |
 
 ### Shebang usage
 With `--keep` and `--gpu` baked into the shebang line, an entire one-file workload becomes:

{google_colab_cli-0.5.7 → google_colab_cli-0.5.9}/integration/README.md

@@ -16,6 +16,8 @@ End-to-end tests that run against a **live Colab backend** (unlike the mocked un
 | `repro_keep_alive_scope/` | Slow soak test (~95s): runs the daemon long enough for one ping past the pre-flight, asserts no `keep_alive_error` events. |
 | `repro_variable_persistence/` | Variables persist across `colab exec` calls in the same session. |
 | `repro_piped_console/` | Fast smoke test (~5s including session creation): `echo cmd \| colab console -s s` runs the command and exits within 30s. Regression test for the 2026-05-07 EOF-handler fix. |
+| `repro_bundled_oauth/` | Fast smoke test (~5s): verifies that the fallback OAuth configuration is loaded and starts the OAuth flow with the default client ID when local config is missing. |
+
 
 ## Running
 ```bash

google_colab_cli-0.5.9/integration/repro_bundled_oauth/test.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Integration Test: Fallback OAuth Configuration Verification
+#
+# This test verifies that the CLI correctly falls back to using the bundled
+# oauth_config.json containing the default client ID when no local config is present.
+# It simulates a fresh user flow by temporarily hiding existing tokens/configs,
+# starting the OAuth flow, and asserting that the printed authorization URL
+# contains the correct Client ID.
+#
+
+set -e
+
+TOKEN_PATH="$HOME/.config/colab-cli/token.json"
+CONFIG_PATH="$HOME/.colab-cli-oauth-config.json"
+BACKUP_SUFFIX=".backup.$(date +%s)"
+
+TOKEN_BACKUP=""
+CONFIG_BACKUP=""
+
+cleanup() {
+    echo "[*] Cleaning up backups..."
+    if [ -n "$TOKEN_BACKUP" ] && [ -f "$TOKEN_BACKUP" ]; then
+        mv "$TOKEN_BACKUP" "$TOKEN_PATH"
+        echo "[*] Restored token.json"
+    fi
+    if [ -n "$CONFIG_BACKUP" ] && [ -f "$CONFIG_BACKUP" ]; then
+        mv "$CONFIG_BACKUP" "$CONFIG_PATH"
+        echo "[*] Restored .colab-cli-oauth-config.json"
+    fi
+}
+trap cleanup EXIT
+
+# 1. Back up existing configuration files if they exist
+if [ -f "$TOKEN_PATH" ]; then
+    TOKEN_BACKUP="${TOKEN_PATH}${BACKUP_SUFFIX}"
+    mv "$TOKEN_PATH" "$TOKEN_BACKUP"
+    echo "[*] Temporarily backed up token.json to $TOKEN_BACKUP"
+fi
+
+if [ -f "$CONFIG_PATH" ]; then
+    CONFIG_BACKUP="${CONFIG_PATH}${BACKUP_SUFFIX}"
+    mv "$CONFIG_PATH" "$CONFIG_BACKUP"
+    echo "[*] Temporarily backed up .colab-cli-oauth-config.json to $CONFIG_BACKUP"
+fi
+
+# 2. Run colab sessions command to trigger the OAuth flow
+echo "[*] Running 'colab --auth=oauth2 sessions' (expecting to trigger browser flow)..."
+# We expect the command to block waiting for authorization, so we run it with a timeout.
+# We redirect output to a file so we can inspect it.
+OUTPUT_LOG=$(mktemp)
+set +e
+PYTHONUNBUFFERED=1 timeout 5 uv run colab --auth=oauth2 sessions > "$OUTPUT_LOG" 2>&1
+EXIT_CODE=$?
+set -e
+
+echo "[*] Command exited with code: $EXIT_CODE"
+echo "----------------- CLI Output -----------------"
+cat "$OUTPUT_LOG"
+echo "----------------------------------------------"
+
+# 3. Assertions
+EXPECTED_CLIENT_ID="764086051850-6qr4p6gpi6hn506pt8ejuq83di341hur.apps.googleusercontent.com"
+
+# The command should have printed the authorization URL
+if ! grep -q "Please visit this URL to authorize this application" "$OUTPUT_LOG"; then
+    echo "[FAILURE] OAuth prompt message not found in output."
+    rm -f "$OUTPUT_LOG"
+    exit 1
+fi
+
+# The URL should contain the correct client ID
+if ! grep -q "client_id=$EXPECTED_CLIENT_ID" "$OUTPUT_LOG"; then
+    echo "[FAILURE] Authorization URL does not contain the expected client ID: $EXPECTED_CLIENT_ID"
+    rm -f "$OUTPUT_LOG"
+    exit 1
+fi
+
+echo "[SUCCESS] Verified that CLI correctly initiated OAuth flow with the fallback Client ID: $EXPECTED_CLIENT_ID"
+rm -f "$OUTPUT_LOG"

{google_colab_cli-0.5.7 → google_colab_cli-0.5.9}/pyproject.toml

@@ -34,6 +34,10 @@ source = "vcs"
 [tool.hatch.build.targets.wheel]
 packages = ["src/colab_cli"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"README.md" = "colab_cli/README.md"
+"COLAB_SKILL.md" = "colab_cli/COLAB_SKILL.md"
+
 [tool.uv]
 package = true
 

{google_colab_cli-0.5.7 → google_colab_cli-0.5.9}/src/colab_cli/auth.py

@@ -15,11 +15,13 @@
 import enum
 import json
 import logging
+from importlib import resources
 import os
 import warnings
 from typing import Optional
 
 import google.auth
+import typer
 from google.auth.transport import requests
 from google.auth.transport.requests import Request
 from google.oauth2.credentials import Credentials
@@ -43,6 +45,7 @@ PUBLIC_SCOPES = [
     "openid",
     "https://www.googleapis.com/auth/userinfo.profile",
     "https://www.googleapis.com/auth/userinfo.email",
+    "https://www.googleapis.com/auth/cloud-platform",
     "https://www.googleapis.com/auth/colaboratory",
     "https://www.googleapis.com/auth/drive.file",
 ]
@@ -60,9 +63,18 @@ def _get_google_auth_credentials(config_path: str) -> Credentials:
     if os.path.exists(config_path):
         with open(config_path, "r") as f:
             client_config = json.load(f)
+    else:
+        # Last resort: try inlined config
+        try:
+            config_resource = resources.files("colab_cli").joinpath("oauth_config.json")
+            if config_resource.is_file():
+                client_config = json.loads(config_resource.read_text())
+        except Exception as e:
+            logger.debug(f"Failed to load inlined config: {e}")
+
     if not client_config:
         raise FileNotFoundError(
-            f"Client OAuth config not found at {config_path}. "
+            f"Client OAuth config not found at {config_path} and no inlined config available. "
             "Please provide a valid path via -c/--client-oauth-config."
         )
 
@@ -137,6 +149,34 @@ def _get_adc_credentials() -> Credentials:
             category=UserWarning,
         )
         creds, _ = google.auth.default(scopes=list(PUBLIC_SCOPES))
+
+
+    if not creds.valid:
+        from google.auth import compute_engine
+
+        if isinstance(creds, compute_engine.Credentials):
+            creds = None
+        else:
+            logger.warning("Failed to obtain valid ADC credentials.")
+            try:
+                logger.warning("Trying to refresh ADC credentials")
+                creds.refresh(Request())
+            except Exception as e:
+                logger.warning(f"Failed to refresh token: {e}")
+                creds = None
+
+    if not creds:
+        typer.echo(
+            "No valid default credentials found. To authenticate, run:\n\n"
+            "  gcloud auth application-default login \\\n"
+            "      --scopes=openid,"
+            "https://www.googleapis.com/auth/cloud-platform,"
+            "https://www.googleapis.com/auth/userinfo.email,"
+            "https://www.googleapis.com/auth/colaboratory\n",
+            err=True,
+        )
+        exit(1)
+
     # Some credential subclasses ignore the `scopes=` kwarg in `default()`
     # (e.g. user creds), so re-apply via `with_scopes` when supported.
     if getattr(creds, "requires_scopes", False):