Skip to content

Document external CLI server connection #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SteveSandersonMS merged 4 commits into from
Jan 23, 2026
Merged

Document external CLI server connection #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
271e660
Initial plan
Copilot Jan 22, 2026
db4f272
Add documentation for connecting to external CLI server
Copilot Jan 22, 2026
729c9f3
Apply suggestions from code review
SteveSandersonMS Jan 23, 2026
8f8365a
Apply suggestions from code review
SteveSandersonMS Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
101 changes: 101 additions & 0 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Comment on lines +885 to +888
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
<details open>
<summary><strong>Node.js / TypeScript</strong></summary>

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

const client = new CopilotClient({
cliUrl: "localhost:4321"
});

// Use the client normally
const session = await client.createSession();
// ...
```

</details>

<details>
<summary><strong>Python</strong></summary>

```python
from copilot import CopilotClient

client = CopilotClient({
"cli_url": "localhost:4321"
})
await client.start()

# Use the client normally
session = await client.create_session()
# ...
Comment on lines +910 to +919
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
```

</details>

<details>
<summary><strong>Go</strong></summary>

```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()
// ...
Comment on lines +928 to +941
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
```

</details>

<details>
<summary><strong>.NET</strong></summary>

```csharp
using GitHub.Copilot.SDK;

using var client = new CopilotClient(new CopilotClientOptions
{
CliUrl = "localhost:4321"
});

// Use the client normally
await using var session = await client.CreateSessionAsync();
// ...
```

</details>

**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)
Expand Down
Loading