Skip to content

bundled-cli.md

Latest commit

 

History

History
286 lines (206 loc) · 8.94 KB

bundled-cli.md

File metadata and controls

286 lines (206 loc) · 8.94 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

Note

Each SDK has a minimum language runtime requirement—see the Prerequisites section of the Node.js, Python, Go, Rust, Java, or .NET README—since an unsupported runtime (e.g. Python below the stated floor) can cause pip/package managers to silently resolve an outdated SDK release instead of reporting a version conflict.

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

const client = new CopilotClient();

const session = await client.createSession({ model: "auto" });
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
from copilot.session_events import AssistantMessageData

client = CopilotClient()
await client.start()

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="auto")
response = await session.send_and_wait("Hello!")
if response and isinstance(response.data, AssistantMessageData):
    print(response.data.content)

await client.stop()
Go

[!NOTE] Unlike the Node.js, Python, and .NET SDKs, the Go SDK does not provide a CLI automatically. With no explicit path, NewClient(nil) uses COPILOT_CLI_PATH when it is set, then the embedded CLI. It does not look up copilot on PATH, so starting the client fails when neither is available. 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: "auto"})
	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: "auto"})
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 = "auto" });

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

[!NOTE] The Java SDK artifact does not include the Copilot CLI. By default, the client starts the CLI from the platform runtime JAR: add the com.github:copilot-sdk-java-runtime dependency with your platform's classifier, such as linux-x64. Alternatively, install the CLI separately and set its location with setCliPath(...) or COPILOT_CLI_PATH (or connect to a running CLI server with setCliUrl(...)). The client does not look up copilot on your PATH.

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("auto")
    .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.

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

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:

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

// Your application's own way of getting the user's token
declare function getUserToken(): string;

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:

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

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:

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

// The project the user has open in your app
declare const projectName: string;

const client = new CopilotClient();

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

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