From 271e660bc611b75dd2b900de028e4f40943f3f64 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 23:10:56 +0000 Subject: [PATCH 1/4] Initial plan From db4f2723cb5d15880e5191923b990de4a79483b5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 23:13:59 +0000 Subject: [PATCH 2/4] Add documentation for connecting to external CLI server Co-authored-by: friggeri <106686+friggeri@users.noreply.github.com> --- README.md | 2 +- docs/getting-started.md | 101 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3130f836..44f0937b 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Your Application Copilot CLI (server mode) ``` -The SDK manages the CLI process lifecycle automatically. You can also connect to an external CLI server—see individual SDK docs for details. +The SDK manages the CLI process lifecycle automatically. You can also connect to an external CLI server—see the [Getting Started Guide](./docs/getting-started.md#connecting-to-an-external-cli-server) for details on running the CLI in server mode. ## FAQ diff --git a/docs/getting-started.md b/docs/getting-started.md index 7833d074..2dcb3346 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -864,6 +864,107 @@ const session = await client.createSession({ --- +## Connecting to an External CLI Server + +By default, the SDK automatically manages the Copilot CLI process lifecycle—starting and stopping the CLI as needed. However, you can also run the CLI in server mode separately and have the SDK connect to it. This can be useful for: + +- **Debugging**: Keep the CLI running between SDK restarts to inspect logs +- **Resource sharing**: Multiple SDK clients can connect to the same CLI server +- **Development**: Run the CLI with custom settings or in a different environment + +### Running the CLI in Server Mode + +Start the CLI in server mode using the `--server` flag and optionally specify a port: + +```bash +copilot --server --port 4321 +``` + +If you don't specify a port, the CLI will choose a random available port. + +### Connecting the SDK to the External Server + +Once the CLI is running in server mode, configure your SDK client to connect to it using the `cli_url` option: + +
+Node.js / TypeScript + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient({ + cliUrl: "localhost:4321" +}); + +// Use the client normally +const session = await client.createSession({ model: "gpt-4.1" }); +// ... +``` + +
+ +
+Python + +```python +from copilot import CopilotClient + +client = CopilotClient({ + "cli_url": "localhost:4321" +}) +await client.start() + +# Use the client normally +session = await client.create_session({"model": "gpt-4.1"}) +# ... +``` + +
+ +
+Go + +```go +import copilot "github.com/github/copilot-sdk/go" + +client := copilot.NewClient(&copilot.ClientOptions{ + CLIUrl: "localhost:4321", +}) + +if err := client.Start(); err != nil { + log.Fatal(err) +} +defer client.Stop() + +// Use the client normally +session, err := client.CreateSession(&copilot.SessionConfig{Model: "gpt-4.1"}) +// ... +``` + +
+ +
+.NET + +```csharp +using GitHub.Copilot.SDK; + +var client = new CopilotClient(new CopilotClientOptions +{ + CliUrl = "localhost:4321" +}); + +// Use the client normally +var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" }); +// ... +``` + +
+ +**Note:** When `cli_url` / `cliUrl` / `CLIUrl` is provided, the SDK will not spawn or manage a CLI process—it will only connect to the existing server at the specified URL. + +--- + ## Learn More - [Node.js SDK Reference](../nodejs/README.md) From 729c9f3fbdd2b1293815baebd1e061d688dd3a47 Mon Sep 17 00:00:00 2001 From: Steve Sanderson Date: Fri, 23 Jan 2026 11:09:10 +0000 Subject: [PATCH 3/4] Apply suggestions from code review --- docs/getting-started.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 2dcb3346..1811688f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -866,7 +866,7 @@ const session = await client.createSession({ ## Connecting to an External CLI Server -By default, the SDK automatically manages the Copilot CLI process lifecycle—starting and stopping the CLI as needed. However, you can also run the CLI in server mode separately and have the SDK connect to it. This can be useful for: +By default, the SDK automatically manages the Copilot CLI process lifecycle, starting and stopping the CLI as needed. However, you can also run the CLI in server mode separately and have the SDK connect to it. This can be useful for: - **Debugging**: Keep the CLI running between SDK restarts to inspect logs - **Resource sharing**: Multiple SDK clients can connect to the same CLI server @@ -884,7 +884,7 @@ If you don't specify a port, the CLI will choose a random available port. ### Connecting the SDK to the External Server -Once the CLI is running in server mode, configure your SDK client to connect to it using the `cli_url` option: +Once the CLI is running in server mode, configure your SDK client to connect to it using the "cli url" option:
Node.js / TypeScript @@ -897,7 +897,7 @@ const client = new CopilotClient({ }); // Use the client normally -const session = await client.createSession({ model: "gpt-4.1" }); +const session = await client.createSession(); // ... ``` @@ -915,7 +915,7 @@ client = CopilotClient({ await client.start() # Use the client normally -session = await client.create_session({"model": "gpt-4.1"}) +session = await client.create_session() # ... ``` @@ -937,7 +937,7 @@ if err := client.Start(); err != nil { defer client.Stop() // Use the client normally -session, err := client.CreateSession(&copilot.SessionConfig{Model: "gpt-4.1"}) +session, err := client.CreateSession() // ... ``` @@ -955,13 +955,13 @@ var client = new CopilotClient(new CopilotClientOptions }); // Use the client normally -var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" }); +await using var session = await client.CreateSessionAsync(); // ... ```
-**Note:** When `cli_url` / `cliUrl` / `CLIUrl` is provided, the SDK will not spawn or manage a CLI process—it will only connect to the existing server at the specified URL. +**Note:** When `cli_url` / `cliUrl` / `CLIUrl` is provided, the SDK will not spawn or manage a CLI process - it will only connect to the existing server at the specified URL. --- From 8f8365ae997ad648bbded193a5ca8b128acd627a Mon Sep 17 00:00:00 2001 From: Steve Sanderson Date: Fri, 23 Jan 2026 11:09:28 +0000 Subject: [PATCH 4/4] Apply suggestions from code review --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 1811688f..2f275f4e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -949,7 +949,7 @@ session, err := client.CreateSession() ```csharp using GitHub.Copilot.SDK; -var client = new CopilotClient(new CopilotClientOptions +using var client = new CopilotClient(new CopilotClientOptions { CliUrl = "localhost:4321" });