google-colab-cli 0.5.7__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.7 → google_colab_cli-0.5.8}/docs/04_automation_and_utility.md

@@ -1,5 +1,7 @@
 ---
 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.
@@ -184,10 +186,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 +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
@@ -286,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.7 → google_colab_cli-0.5.8}/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.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 google-colab-cli",
+                _get_install_command(),
                 show_disable_hint=quiet,
             )
         elif not quiet:
@@ -211,10 +231,6 @@ 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:
     """Upgrade the CLI in place, detecting uv vs pip."""
     import sys

{google_colab_cli-0.5.7 → 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.7 → 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.7 → 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)
@@ -505,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)

{google_colab_cli-0.5.7 → google_colab_cli-0.5.8}/src/colab_cli/commands/utility.py

@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import platform
 from typing import Optional
 
 import typer
@@ -362,9 +361,10 @@ def update_command(
     if not install:
         return
 
-    if platform.system() != "Linux":
+    if not auto_update.is_self_install_supported():
         typer.echo(
-            "[colab] '--install' self-install is only supported on Linux.", err=True
+            "[colab] '--install' self-install is only supported on Linux and macOS.",
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -379,6 +379,48 @@ def update_command(
     auto_update.self_install()
 
 
+def _print_resource(filename: str) -> None:
+    import importlib.resources
+    import os
+
+    content = None
+    try:
+        # Try reading from package resources
+        ref = importlib.resources.files("colab_cli").joinpath(filename)
+        if ref.is_file():
+            content = ref.read_text(encoding="utf-8")
+    except Exception:
+        pass
+
+    if not content:
+        # Fallback to local file for development
+        local_path = os.path.abspath(
+            os.path.join(os.path.dirname(__file__), f"../../../{filename}")
+        )
+        if os.path.exists(local_path):
+            try:
+                with open(local_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+            except Exception:
+                pass
+
+    if content:
+        typer.echo(content)
+    else:
+        typer.echo(f"[colab] {filename} content not available.", err=True)
+        raise typer.Exit(code=1)
+
+
+def readme():
+    """Print the bundled README.md file"""
+    _print_resource("README.md")
+
+
+def skill():
+    """Print the bundled COLAB_SKILL.md file"""
+    _print_resource("COLAB_SKILL.md")
+
+
 def register(app: typer.Typer):
     app.command()(pay)
     app.command()(log)
@@ -388,3 +430,7 @@ def register(app: typer.Typer):
     # Developer-only debugging aid; hidden from `colab --help` but still
     # reachable via `colab whoami` / `colab whoami --help`.
     app.command(name="whoami", hidden=True)(whoami)
+    app.command(name="readme")(readme)
+    app.command(name="README", hidden=True)(readme)
+    app.command(name="skill")(skill)
+    app.command(name="SKILL", hidden=True)(skill)

{google_colab_cli-0.5.7 → google_colab_cli-0.5.8}/src/colab_cli/runtime.py

@@ -154,7 +154,7 @@ class ColabRuntime:
                     raise e
 
         return self._kernel_client
-    
+
     def restart(
         self,
         timeout: Optional[float] = None,