Python: switch from bundled CLI wheels to downloading explicitly or at runtime

.github/workflows/publish.yml

@@ -214,8 +214,10 @@ jobs:
         run: npm ci --ignore-scripts
       - name: Set version
         run: sed -i "s/^version = .*/version = \"${{ needs.version.outputs.version }}\"/" pyproject.toml
-      - name: Build platform wheels
-        run: node scripts/build-wheels.mjs --output-dir dist
+      - name: Inject CLI version
+        run: node scripts/inject-cli-version.mjs
+      - name: Build wheel
+        run: uv build --wheel --out-dir dist
       - name: Upload artifact
         uses: actions/upload-artifact@v7.0.0
         with:

docs/getting-started.md

@@ -18,7 +18,7 @@ Copilot: In Tokyo it's 75°F and sunny. Great day to be outside!
 
 Before you begin, make sure you have:
 
-* **GitHub Copilot CLI** installed and authenticated (the Node.js, Python, and .NET SDKs bundle the CLI automatically—see [Bundled CLI](./setup/bundled-cli.md). Required for Go, Java, and Rust unless using their application-level CLI bundling features.)
+* **GitHub Copilot CLI** installed and authenticated (the Node.js, Python, and .NET SDKs provide the CLI automatically—see [Bundled CLI](./setup/bundled-cli.md). Required for Go, Java, and Rust unless using their application-level CLI bundling features.)
 * Your preferred language runtime:
   * **Node.js** 20+ or **Python** 3.11+ or **Go** 1.24+ or **Rust** 1.94+ or **Java** 17+ or **.NET** 8.0+
 

docs/setup/bundled-cli.md

@@ -1,12 +1,20 @@
 # Default setup (bundled CLI)
 
-The Node.js, Python, and .NET SDKs include the Copilot CLI as a dependency—your app ships with everything it needs, with no extra installation or configuration required.
+The Node.js and .NET SDKs include the Copilot CLI as a dependency—your app ships with everything it needs, with no extra installation or configuration required.
+
+The Python SDK recommends a one-time download step after installation:
+
+```bash
+python -m copilot download-runtime
+```
+
+This downloads the matching runtime and caches it locally. If you skip this step, the SDK will attempt to download it automatically on first use as a fallback.
 
 **Best for:** Most applications—desktop apps, standalone tools, CLI utilities, prototypes, and more.
 
 ## How it works
 
-When you install the SDK, the Copilot CLI binary is included automatically. The SDK starts it as a child process and communicates over stdio. There's nothing extra to configure.
+When you install the SDK, the Copilot runtime is included automatically (Node.js, .NET) or downloaded via `python -m copilot download-runtime` (Python). The SDK starts it as a child process and communicates over stdio. There's nothing extra to configure.
 
 ```mermaid
 flowchart TB

docs/setup/local-cli.md

@@ -1,6 +1,6 @@
 # Local CLI setup
 
-Use a specific CLI binary instead of the SDK's bundled CLI. This is an advanced option—you supply the CLI path explicitly, and you are responsible for ensuring version compatibility with the SDK.
+Use a specific CLI binary instead of the SDK's automatic CLI management. This is an advanced option—you supply the CLI path explicitly, and you are responsible for ensuring version compatibility with the SDK.
 
 **Use when:** You need to pin a specific CLI version, or work with the Go SDK (which does not bundle a CLI).
 

python/.gitignore

@@ -169,6 +169,3 @@ uv.lock
 # Build script caches
 .cli-cache/
 .build-temp/
-
-# Bundled CLI binary (only in platform wheels, not in repo)
-copilot/bin/

python/README.md

@@ -20,6 +20,33 @@ To include OpenTelemetry support:
 pip install "github-copilot-sdk[telemetry]"
 ```
 
+## Runtime
+
+Published wheels include a pinned runtime version. After installing, download the
+runtime:
+
+```bash
+python -m copilot download-runtime
+```
+
+This caches the runtime binary locally. If you skip this step, the SDK will
+attempt to download it automatically on first use as a fallback.
+
+| Platform | Cache path |
+|----------|-----------|
+| Linux | `~/.cache/github-copilot-sdk/cli/<version>/copilot` |
+| macOS | `~/Library/Caches/github-copilot-sdk/cli/<version>/copilot` |
+| Windows | `%LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe` |
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `COPILOT_CLI_PATH` | Use this specific binary instead of downloading |
+| `COPILOT_CLI_EXTRACT_DIR` | Override the cache directory (binary placed directly here) |
+| `COPILOT_SKIP_CLI_DOWNLOAD` | Set to `1` to disable auto-download |
+| `COPILOT_CLI_DOWNLOAD_BASE_URL` | Override the GitHub Releases download URL |
+
 ## Run the Sample
 
 Try the interactive chat sample (from the repo root):

python/copilot/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m copilot`."""
+
+from ._cli_download import main
+
+if __name__ == "__main__":
+    main()