Document external CLI server connection

[Copilot]

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

• README.md: Link to new getting-started section instead of vague reference to "individual SDK docs"
• docs/getting-started.md: Add "Connecting to an External CLI Server" section with:
  • Command to run CLI in server mode: copilot --server --port 4321
  • Configuration examples for all four SDKs (Node.js, Python, Go, .NET)
  • Use cases: debugging, resource sharing, custom environments

Example

// Start external CLI server: copilot --server --port 4321

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
    cliUrl: "localhost:4321"  // Connect to external server
});

const session = await client.createSession({ model: "gpt-4.1" });

Original prompt

---

This section details on the original issue you should resolve

<issue_title>How to connect to external CLI server?</issue_title>
<issue_description>The doc says "The SDK manages the CLI process lifecycle automatically. You can also connect to an external CLI server—see individual SDK docs for details." but I don't find the details. </issue_description>

<agent_instructions>Add documentation in the right place to describe how to run the CLI in server mode so that the SDK can connect to it. @friggeri gave an example in one of the comments on this PR</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@friggeri You can run the CLI in server mode and specify a port using the following command: `copilot --server --port [number]`, you can then pass the url to that to the SDK client. For example in Python:

# start the CLI in server mode by running: copilot --server --port=4321
client = CopilotClient({
    "cli_url": "localhost:4321"
})

I agree with you we should add documentation for how to run the CLI in server mode. </comment_new>

• Fixes How to connect to external CLI server? #101

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

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/handle err. 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 is CliUrl (as used in the example above and in dotnet/README.md). Please include CliUrl here 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.

[Copilot]

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

[Copilot]

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).

Suggested change

	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())

[Copilot]

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

Suggested change

	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
	// ...
	}

[Copilot]

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.

Suggested change

	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" });