Document external CLI server connection #103
Conversation
Co-authored-by: friggeri <106686+friggeri@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds missing documentation for connecting SDKs to a separately-run Copilot CLI server (“server mode”), and updates the README to point to the new guidance.
Changes:
- Adds a new “Connecting to an External CLI Server” section to the Getting Started guide (CLI server command + SDK configuration examples).
- Updates README to link directly to the new Getting Started section instead of referencing vague “individual SDK docs”.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/getting-started.md | Adds external CLI server instructions and per-SDK connection examples. |
| README.md | Links to the new Getting Started section for external CLI server connection instructions. |
Comments suppressed due to low confidence (2)
docs/getting-started.md:941
client.CreateSession(...)returns(session, err)here but the example doesn’t check/handleerr. Please add the error handling (consistent with earlier Go snippets in this doc) so readers don’t copy/paste a pattern that will fail silently or panic later.
// Use the client normally
session, err := client.CreateSession(&copilot.SessionConfig{Model: "gpt-4.1"})
// ...
docs/getting-started.md:964
- This note lists
cli_url/cliUrl/CLIUrl, but the .NET SDK option/property isCliUrl(as used in the example above and in dotnet/README.md). Please includeCliUrlhere to avoid implying the wrong casing for .NET.
**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.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### 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: | ||
|
|
There was a problem hiding this comment.
The prose says to configure the client using the cli_url option, but only the Python SDK uses cli_url. Node uses cliUrl, Go uses CLIUrl, and .NET uses CliUrl. Reword this sentence to be language-agnostic (e.g., “set the CLI URL option”) or mention the per-SDK option names explicitly here to avoid confusing readers before the code samples.
This issue also appears in the following locations of the same file:
- line 964
| 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"}) | ||
| # ... |
There was a problem hiding this comment.
The Python example uses await at top level, which won’t run in a normal main.py script. Please wrap this in an async def main(): ... and call asyncio.run(main()) (consistent with earlier Python snippets in this guide).
| 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"}) | |
| # ... | |
| import asyncio | |
| from copilot import CopilotClient | |
| async def main(): | |
| client = CopilotClient({ | |
| "cli_url": "localhost:4321" | |
| }) | |
| await client.start() | |
| # Use the client normally | |
| session = await client.create_session({"model": "gpt-4.1"}) | |
| # ... | |
| if __name__ == "__main__": | |
| asyncio.run(main()) |
| 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"}) | ||
| // ... |
There was a problem hiding this comment.
The Go snippet isn’t a complete/compilable example as written (missing package main and a proper import (...) block, and it uses log.Fatal without importing log). Please align this with the earlier Go examples in this guide by providing a minimal full program.
This issue also appears in the following locations of the same file:
- line 939
| 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"}) | |
| // ... | |
| package main | |
| import ( | |
| "log" | |
| copilot "github.com/github/copilot-sdk/go" | |
| ) | |
| func main() { | |
| 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"}) | |
| if err != nil { | |
| log.Fatal(err) | |
| } | |
| _ = session | |
| // ... | |
| } |
docs/getting-started.md
Outdated
| var client = new CopilotClient(new CopilotClientOptions | ||
| { | ||
| CliUrl = "localhost:4321" | ||
| }); | ||
|
|
||
| // Use the client normally | ||
| var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" }); |
There was a problem hiding this comment.
The .NET snippet should dispose the CopilotClient (and typically the session) to ensure the connection/process is cleaned up. Elsewhere in this guide, the pattern is await using var client = .... Please update this example to follow that pattern.
| var client = new CopilotClient(new CopilotClientOptions | |
| { | |
| CliUrl = "localhost:4321" | |
| }); | |
| // Use the client normally | |
| var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" }); | |
| await using var client = new CopilotClient(new CopilotClientOptions | |
| { | |
| CliUrl = "localhost:4321" | |
| }); | |
| // Use the client normally | |
| await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" }); |
The README referenced connecting to an external CLI server but provided no instructions. Users needed to know how to run the CLI in server mode and configure the SDK to connect to it.
Changes
copilot --server --port 4321Example
Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.