google-colab-cli 0.5.6__tar.gz → 0.5.8__tar.gz

google_colab_cli-0.5.8/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: google-colab-cli
+Version: 0.5.8
+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.8/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.6 → google_colab_cli-0.5.8}/docs/04_automation_and_utility.md

@@ -1,5 +1,10 @@
 ---
 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-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.
 2026-05-07: Added a developer-only `colab whoami` subcommand (hidden from `colab --help`). Mints an access token via the same `auth.get_credentials(...)` path the rest of the CLI uses (honoring the global `--auth=...` flag), refreshes the credentials, then queries `https://oauth2.googleapis.com/tokeninfo` to print the email, scopes, audience, and expiry of whatever the CLI is about to send. Built specifically to short-circuit the "why is my call to colab.pa.googleapis.com 403-ing" debugging loop — the answer is almost always "missing scope" or "wrong identity", both of which `whoami` makes immediately visible. Hidden via `app.command(hidden=True)`; reachable via `colab whoami` or `colab whoami --help`. Suppressed from the daily-update banner check (added to `_AUTO_UPDATE_SUPPRESSED` in `cli.py`) so the banner doesn't obscure the auth output.
 2026-05-11: Removed the local-file update source (`update_file_path` setting and `_fetch_local` helper); `colab update` now consults PyPI only. Switched the default `update_url` to the canonical PyPI JSON API (`https://pypi.org/pypi/google-colab-cli/json`), which already exposes the `info.version` schema the auto-update subsystem expects. Re-added `colab update --install` as a public self-install path that runs `pip install -U google-colab-cli` against the current `sys.executable`; Linux-only (other platforms exit non-zero with an explanatory message), and a silent no-op when the cached `latest_version` is already at or below the current install.
 2026-05-12: Added an optional `timeout=` parameter to `ColabRuntime.execute_code` that flows through to both the `execute()` and `execute_interactive()` branches. `colab auth` and `colab drivemount` now pass `timeout=600` (10 min) via a shared `INTERACTIVE_AUTOMATION_TIMEOUT_SEC` constant in `commands/automation.py`. Background: `jupyter_kernel_client` defaults to a 10s wall-clock timeout that is consumed even when the kernel is idle waiting on `input_request`. With the drivefs hook intercepting that request and prompting the user to OAuth in their browser, any user that takes >10s to click through (essentially everyone) hit `TimeoutError` and saw "drivemount failed" even though the mount had actually succeeded server-side. The fix is scoped narrowly to the two human-in-the-loop subcommands; non-interactive paths (`colab exec`, `colab run`, `colab install`, `colab repl --pipe`, `colab console --pipe`) keep the upstream default since they receive continuous iopub traffic that resets the practical inactivity ceiling.
@@ -180,18 +185,23 @@ remediation guidance) rather than silently after ~1 minute via the daemon.
             across failed checks so transient network issues do not erase
             the cache.
 -   **Notification**: If a new version is found, a non-intrusive message is
-    printed to the console with a `Run 'pip install --upgrade colab' to
-    update.` hint. The cached banner shown between fetches uses the generic
-    `Run 'colab update' to update.` hint.
+    printed to the console with a `Run 'pip install --upgrade google-colab-cli' to
+    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` shell out to `pip install -U
-    google-colab-cli` (using `sys.executable` so the upgrade lands in the
-    same interpreter the CLI is running under). **Linux only**; on other
-    platforms the command exits non-zero with an explanatory message. When
-    the cached `latest_version` is already at or below the current install,
-    the flag is a silent no-op so it is safe to wire into automation. If
-    `pip` exits non-zero, `colab update --install` propagates the same
-    exit code.
+    `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`.
+    - Otherwise, runs `pip install -U google-colab-cli` using `sys.executable`
+      to ensure the upgrade lands in the same interpreter.
+    On other platforms, the command exits non-zero with an explanatory
+    message. When the cached `latest_version` is already at or below the
+    current install, the flag is a silent no-op so it is safe to wire into
+    automation. If the upgrade command exits non-zero, `colab update --install`
+    propagates the same exit code.
 
 ### 8. Identity Inspection (`colab whoami`) [developer-only]
 
@@ -235,6 +245,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
@@ -280,3 +303,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.6 → google_colab_cli-0.5.8}/pyproject.toml

@@ -14,9 +14,6 @@ dependencies = [
     "prompt-toolkit>=3.0.52",
     "pydantic>=2.12.5",
     "pygments>=2.19.2",
-    "pytest>=9.0.2",
-    "pytest-cov>=7.0.0",
-    "pytest-mock>=3.15.1",
     "requests>=2.32.5",
     "rich>=14.3.3",
     "typer>=0.24.1",
@@ -37,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
 
@@ -48,5 +49,8 @@ jupyter-kernel-client = { git = "https://github.com/googlecolab/jupyter-kernel-c
 
 [dependency-groups]
 dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.15.1",
     "ruff>=0.15.6",
 ]

{google_colab_cli-0.5.6 → google_colab_cli-0.5.8}/src/colab_cli/auto_update.py

@@ -23,6 +23,7 @@ callback (``cli.py``) calls ``check_for_updates`` once per day and
 """
 
 import json
+import platform
 import subprocess
 import urllib.request
 from datetime import datetime, timezone
@@ -35,10 +36,18 @@ import typer
 from colab_cli.common import state
 from colab_cli.state import Settings
 
+# PyPI distribution name (different from the importable package name `colab`).
+PYPI_PACKAGE_NAME = "google-colab-cli"
+
 
 # ---------- Version detection -------------------------------------------
 
 
+def is_self_install_supported() -> bool:
+    """Return True if self-install (--install) is supported on the current platform."""
+    return platform.system() in ("Linux", "Darwin")
+
+
 def get_app_version() -> str:
     """Return the installed package version, falling back to the git short hash."""
     try:
@@ -109,6 +118,8 @@ def announce_upgrade(
     typer.echo(
         f"\n[colab] A new version of Colab CLI is available: {latest} (current: {current})"
     )
+    if is_self_install_supported() and ("pip" in install_cmd or "uv" in install_cmd):
+        typer.echo("[colab] You can run 'colab update --install' to upgrade in place.")
     typer.echo(f"[colab] Run '{install_cmd}' to update.")
     if show_disable_hint:
         typer.echo(
@@ -122,6 +133,15 @@ def announce_upgrade(
 # ---------- Orchestration -----------------------------------------------
 
 
+def _get_install_command() -> str:
+    """Return the recommended installation command based on the environment."""
+    import sys
+
+    if is_self_install_supported() and "/uv/tools/" in sys.executable:
+        return f"uv tool install -U {PYPI_PACKAGE_NAME}"
+    return f"pip install --upgrade {PYPI_PACKAGE_NAME}"
+
+
 def check_for_updates(quiet: bool = False) -> None:
     """Check PyPI for updates and print a message if a new version is available.
 
@@ -140,7 +160,7 @@ def check_for_updates(quiet: bool = False) -> None:
             announce_upgrade(
                 pypi_v,
                 current,
-                "pip install --upgrade colab",
+                _get_install_command(),
                 show_disable_hint=quiet,
             )
         elif not quiet:
@@ -211,15 +231,17 @@ def run_background_check() -> None:
 # ---------- Self-install ------------------------------------------------
 
 
-# PyPI distribution name (different from the importable package name `colab`).
-PYPI_PACKAGE_NAME = "google-colab-cli"
-
-
 def self_install() -> None:
-    """Run ``pip install -U <PYPI_PACKAGE_NAME>`` to upgrade the CLI in place."""
+    """Upgrade the CLI in place, detecting uv vs pip."""
     import sys
 
-    cmd = [sys.executable, "-m", "pip", "install", "-U", PYPI_PACKAGE_NAME]
+    # If the executable path contains "/uv/", we assume it was installed via
+    # `uv tool install` and use `uv` to upgrade it.
+    if "/uv/tools/" in sys.executable:
+        cmd = ["uv", "tool", "install", "-U", PYPI_PACKAGE_NAME]
+    else:
+        cmd = [sys.executable, "-m", "pip", "install", "-U", PYPI_PACKAGE_NAME]
+
     typer.echo(f"[colab] Running: {' '.join(cmd)}")
     result = subprocess.run(cmd)
     if result.returncode != 0:

{google_colab_cli-0.5.6 → google_colab_cli-0.5.8}/src/colab_cli/cli.py

@@ -105,6 +105,10 @@ def callback(
         "help",
         "url",
         "whoami",
+        "readme",
+        "README",
+        "skill",
+        "SKILL",
     }
     if ctx.invoked_subcommand not in _AUTO_UPDATE_SUPPRESSED:
         auto_update.run_background_check()

{google_colab_cli-0.5.6 → google_colab_cli-0.5.8}/src/colab_cli/commands/run.py

@@ -234,7 +234,7 @@ def run_command(
         ),
     ] = False,
 ):
-    """Run a Python script on a fresh Colab VM, then release the VM.
+    """Run a Python script on a fresh Colab VM, then release the VM
 
     Designed to be used as a shebang interpreter, e.g.
 

{google_colab_cli-0.5.6 → google_colab_cli-0.5.8}/src/colab_cli/commands/session.py

@@ -27,7 +27,6 @@ from colab_cli.client import (
     PostAssignmentResponse,
     Variant,
 )
-from colab_cli.commands.automation import INTERACTIVE_AUTOMATION_TIMEOUT_SEC
 from colab_cli.utils import get_status_code
 from colab_cli.state import SessionState
 from colab_cli.runtime import ColabRuntime
@@ -247,11 +246,12 @@ def new(
     typer.echo("[colab] Session READY.")
 
 
-def restart( 
+def restart_kernel(
     session: Annotated[
         Optional[str], typer.Option("-s", "--session", help="Session name")
     ] = None,
 ):
+    """Restart a session's kernel"""
     from colab_cli.common import state
 
     name = state.resolve_session(session)
@@ -274,7 +274,10 @@ def restart(
         on_session_started=on_sess_started,
     )
 
-    runtime.restart(timeout=INTERACTIVE_AUTOMATION_TIMEOUT_SEC)
+    try:
+        runtime.restart()
+    finally:
+        runtime.stop()
 
 
 def sessions_command():
@@ -502,7 +505,7 @@ def keep_alive(
 def register(app: typer.Typer):
     app.command()(new)
     app.command(name="sessions")(sessions_command)
-    app.command()(restart)
+    app.command(name="restart-kernel")(restart_kernel)
     app.command()(status)
     app.command()(stop)
     app.command(hidden=True)(keep_alive)