Optionally download CLI at runtime in Node SDK

Author: SteveSandersonMS

nodejs/.gitignore

@@ -133,5 +133,8 @@ dist
 dist/
 build/
 
+# Generated version constants (regenerated at build time)
+src/generated/
+
 # macOS
 .DS_Store

nodejs/README.md

@@ -55,9 +55,10 @@ new CopilotClient(options?: CopilotClientOptions)
 
 **Options:**
 
-- `cliPath?: string` - Path to CLI executable (default: "copilot" from PATH)
+- `cliPath?: string` - Path to CLI executable (default: "copilot" from PATH). Mutually exclusive with `acquisition`.
 - `cliArgs?: string[]` - Extra arguments prepended before SDK-managed flags (e.g. `["./dist-cli/index.js"]` when using `node`)
-- `cliUrl?: string` - URL of existing CLI server to connect to (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process.
+- `cliUrl?: string` - URL of existing CLI server to connect to (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process. Mutually exclusive with `acquisition`.
+- `acquisition?: AcquisitionOptions` - Auto-download CLI if not present. See [CLI Acquisition](#cli-acquisition). Mutually exclusive with `cliPath` and `cliUrl`.
 - `port?: number` - Server port (default: 0 for random)
 - `useStdio?: boolean` - Use stdio transport instead of TCP (default: true)
 - `logLevel?: string` - Log level (default: "info")
@@ -645,7 +646,63 @@ try {
 ## Requirements
 
 - Node.js >= 18.0.0
-- GitHub Copilot CLI installed and in PATH (or provide custom `cliPath`)
+- GitHub Copilot CLI installed and in PATH, or:
+  - Provide a custom `cliPath`, or
+  - Use `acquisition` to auto-download the CLI (see below)
+
+## CLI Acquisition
+
+The SDK can automatically download and manage the Copilot CLI for you. This is useful when you can't rely on the CLI being pre-installed.
+
+```typescript
+const client = new CopilotClient({
+    acquisition: {
+        downloadDir: "~/.myapp/copilot-cli", // Where to store CLI versions
+    },
+});
+
+await client.start(); // Downloads CLI if needed, then starts
+```
+
+### How it works
+
+1. **Check existing downloads**: Looks for any CLI version in `downloadDir` that is both >= your `minVersion` (if specified) and protocol-compatible with this SDK.
+
+2. **If a suitable version exists**: Uses the highest compatible version. No download needed.
+
+3. **If no suitable version exists**: Downloads the CLI version this SDK was built for.
+
+This means SDK upgrades don't force re-downloads — your existing CLI is reused as long as it still works.
+
+### Options
+
+```typescript
+interface AcquisitionOptions {
+    // Required: Directory for CLI downloads. Should be app-specific.
+    downloadDir: string;
+
+    // Optional: Minimum CLI version required (e.g., "0.0.405").
+    // If your existing version is lower, a new version will be downloaded.
+    minVersion?: string;
+
+    // Optional: Progress callback for download updates.
+    onProgress?: (progress: { bytesDownloaded: number; totalBytes: number }) => void;
+}
+```
+
+### Example with progress reporting
+
+```typescript
+const client = new CopilotClient({
+    acquisition: {
+        downloadDir: path.join(os.homedir(), ".myapp", "copilot-cli"),
+        onProgress: ({ bytesDownloaded, totalBytes }) => {
+            const pct = totalBytes > 0 ? Math.round((bytesDownloaded / totalBytes) * 100) : 0;
+            console.log(`Downloading CLI: ${pct}%`);
+        },
+    },
+});
+```
 
 ## License
 

nodejs/examples/basic-example.ts

@@ -3,6 +3,8 @@
  *--------------------------------------------------------------------------------------------*/
 
 import { z } from "zod";
+import { join } from "node:path";
+import { homedir } from "node:os";
 import { CopilotClient, defineTool } from "../src/index.js";
 
 console.log("🚀 Starting Copilot SDK Example\n");
@@ -20,10 +22,22 @@ const lookupFactTool = defineTool("lookup_fact", {
     handler: ({ topic }) => facts[topic.toLowerCase()] ?? `No fact stored for ${topic}.`,
 });
 
-// Create client - will auto-start CLI server (searches PATH for "copilot")
-const client = new CopilotClient({ logLevel: "info" });
+// Create client with automatic CLI acquisition
+const client = new CopilotClient({
+    logLevel: "info",
+    acquisition: {
+        downloadDir: join(homedir(), ".copilot-sdk-example", "cli"),
+        onProgress: ({ bytesDownloaded, totalBytes }) => {
+            if (totalBytes > 0) {
+                const pct = Math.round((bytesDownloaded / totalBytes) * 100);
+                process.stdout.write(`\r⬇️  Downloading CLI: ${pct}%`);
+            }
+        },
+    },
+});
+
 const session = await client.createSession({ tools: [lookupFactTool] });
-console.log(`✅ Session created: ${session.sessionId}\n`);
+console.log(`\n✅ Session created: ${session.sessionId}\n`);
 
 // Listen to events
 session.on((event) => {

nodejs/package-lock.json

@@ -16,7 +16,8 @@
   },
   "type": "module",
   "scripts": {
-    "clean": "rimraf --glob dist *.tgz",
+    "clean": "rimraf --glob dist *.tgz src/generated",
+    "prebuild": "tsx scripts/generate-versions.ts",
     "build": "tsx esbuild-copilotsdk-nodejs.ts",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -41,11 +42,13 @@
   "license": "MIT",
   "dependencies": {
     "@github/copilot": "^0.0.402",
+    "semver": "^7.7.3",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",
+    "@types/semver": "^7.7.1",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
     "esbuild": "^0.27.2",
@@ -56,7 +59,7 @@
     "prettier": "^3.4.0",
     "quicktype-core": "^23.2.6",
     "rimraf": "^6.1.2",
-    "semver": "^7.7.3",
+    "tar": "^7.5.7",
     "tsx": "^4.20.6",
     "typescript": "^5.0.0",
     "vitest": "^4.0.18"

nodejs/package.json

@@ -0,0 +1,18 @@
+// Generates src/generated/versions.ts from package-lock.json @github/copilot version.
+// Run automatically via prebuild hook.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageLock = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package-lock.json"), "utf-8"));
+const cliVersion = packageLock.packages["node_modules/@github/copilot"].version;
+
+const code = `// Generated by scripts/generate-versions.ts - DO NOT EDIT
+export const PREFERRED_CLI_VERSION = "${cliVersion}";
+`;
+
+fs.mkdirSync(path.join(__dirname, "..", "src", "generated"), { recursive: true });
+fs.writeFileSync(path.join(__dirname, "..", "src", "generated", "versions.ts"), code);
+console.log(`Generated src/generated/versions.ts with PREFERRED_CLI_VERSION="${cliVersion}"`);