Skip to content

bundled-cli.md

Latest commit

 

History

History
266 lines (193 loc) · 7.56 KB

bundled-cli.md

File metadata and controls

266 lines (193 loc) · 7.56 KB
Raw

Default setup (bundled CLI)

The Node.js and .NET SDKs include the Copilot CLI as a dependency—your app ships with everything it needs, with no extra installation or configuration required.

The Python SDK recommends a one-time download step after installation:

python -m copilot download-runtime

This downloads the matching runtime and caches it locally. If you skip this step, the SDK will attempt to download it automatically on first use as a fallback.

Best for: Most applications—desktop apps, standalone tools, CLI utilities, prototypes, and more.

How it works

When you install the SDK, the Copilot runtime is included automatically (Node.js, .NET) or downloaded via python -m copilot download-runtime (Python). The SDK starts it as a child process and communicates over stdio. There's nothing extra to configure.

flowchart TB
    subgraph Bundle["Your Application"]
        App["Application Code"]
        SDK["SDK Client"]
        CLIBin["Copilot CLI Binary<br/>(included with SDK)"]
    end

    App --> SDK
    SDK --> CLIBin
    CLIBin -- "API calls" --> Copilot["☁️ GitHub Copilot"]

    style Bundle fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
Loading

Key characteristics:

  • CLI binary is included with the SDK—no separate install needed
  • The SDK manages the CLI version to ensure compatibility
  • Users authenticate through your app (or use env vars / BYOK)
  • Sessions are managed per-user on their machine

Quick start

Node.js / TypeScript 
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({ model: "gpt-5.4" });
const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();
Python 
from copilot import CopilotClient
from copilot.session import PermissionHandler

client = CopilotClient()
await client.start()

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.4")
response = await session.send_and_wait("Hello!")
print(response.data.content)

await client.stop()
Go

[!NOTE] Unlike Node.js, Python, and .NET, the Go SDK does not include a CLI as an automatic dependency. With no explicit path, NewClient(nil) uses an embedded CLI when available, then falls back to copilot on PATH. To embed a CLI, run the bundler tool at build time. You can also set COPILOT_CLI_PATH or point a Connection at an existing binary. See Local CLI Setup for details.

package main

import (
	"context"
	"fmt"
	"log"
	copilot "github.com/github/copilot-sdk/go"
)

func main() {
	ctx := context.Background()

	client := copilot.NewClient(nil)
	if err := client.Start(ctx); err != nil {
		log.Fatal(err)
	}
	defer client.Stop()

	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-5.4"})
	response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
	if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
		fmt.Println(d.Content)
	}
}
client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-5.4"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
    fmt.Println(d.Content)
}
.NET 
await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(
    new SessionConfig { Model = "gpt-5.4" });

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello!" });
Console.WriteLine(response?.Data.Content);
Java

[!NOTE] The Java SDK does not bundle or embed the Copilot CLI. Install the CLI separately and either make copilot available on your PATH or set its location with setCliPath(...) (or connect to a running CLI server with setCliUrl(...)).

import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient(new CopilotClientOptions()
    // Point to the CLI binary installed on the system
    .setCliPath("/path/to/vendor/copilot")
);
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-5.4")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var response = session.sendAndWait(new MessageOptions()
    .setPrompt("Hello!")).get();
System.out.println(response.getData().content());

client.stop().get();

Authentication strategies

You need to decide how your users will authenticate. Here are the common patterns:

flowchart TB
    App["Bundled App"]

    App --> A["User signs in to CLI<br/>(keychain credentials)"]
    App --> B["App provides token<br/>(OAuth / env var)"]
    App --> C["BYOK<br/>(your own API keys)"]

    A --> Note1["User runs 'copilot' once<br/>to authenticate"]
    B --> Note2["Your app handles login<br/>and passes token"]
    C --> Note3["No GitHub auth needed<br/>Uses your model provider"]

    style App fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
Loading

Option A: user's signed-in credentials (simplest)

The user signs in to the CLI once, and your app uses those credentials. No extra code needed—this is the default behavior.

const client = new CopilotClient();
// Default: uses signed-in user credentials

Option B: token via environment variable

Ship your app with instructions to set a token, or set it programmatically:

const client = new CopilotClient({
    env: {
        COPILOT_GITHUB_TOKEN: getUserToken(),  // Your app provides the token
    },
});

Option C: BYOK (no GitHub auth needed)

If you manage your own model provider keys, users don't need GitHub accounts at all:

const client = new CopilotClient();

const session = await client.createSession({
    model: "gpt-5.4",
    provider: {
        type: "openai",
        baseUrl: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY,
    },
});

See the BYOK guide for full details.

Session management

Apps typically want named sessions so users can resume conversations:

const client = new CopilotClient();

// Create a session tied to the user's project
const sessionId = `project-${projectName}`;
const session = await client.createSession({
    sessionId,
    model: "gpt-5.4",
});

// User closes app...
// Later, resume where they left off
const resumed = await client.resumeSession(sessionId);

Session state persists at ~/.copilot/session-state/{sessionId}/.

When to move on

Need Next Guide
Users signing in with GitHub accounts GitHub OAuth
Run on a server instead of user machines Backend Services
Use your own model keys BYOK

Next steps