Local CLI Setup

Use the Copilot SDK with the CLI already signed in on your machine. This is the simplest configuration — zero auth code, zero infrastructure.

Best for: Personal projects, prototyping, local development, learning the SDK.

How It Works

When you install the Copilot CLI and sign in, your credentials are stored in the system keychain. The SDK automatically starts the CLI as a child process and uses those stored credentials.

flowchart LR
    subgraph YourMachine["Your Machine"]
        App["Your App"] --> SDK["SDK Client"]
        SDK -- "stdio" --> CLI["Copilot CLI<br/>(auto-started)"]
        CLI --> Keychain["🔐 System Keychain<br/>(stored credentials)"]
    end
    CLI -- "API calls" --> Copilot["☁️ GitHub Copilot"]

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

Key characteristics:

• CLI is spawned automatically by the SDK (no setup needed)
• Authentication uses the signed-in user's credentials from the system keychain
• Communication happens over stdio (stdin/stdout) — no network ports
• Sessions are local to your machine

Quick Start

The default configuration requires no options at all:

import { CopilotClient } from "copilot-sdk-supercharged";

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

const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

from copilot import CopilotClient

client = CopilotClient()
await client.start()

session = await client.create_session({"model": "gpt-4.1"})
response = await session.send_and_wait({"prompt": "Hello!"})
print(response.data.content)

await client.stop()

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-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
fmt.Println(*response.Data.Content)

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(
    new SessionConfig { Model = "gpt-4.1" });

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

That's it. The SDK handles everything: starting the CLI, authenticating, and managing the session.

What's Happening Under the Hood

sequenceDiagram
    participant App as Your App
    participant SDK as SDK Client
    participant CLI as Copilot CLI
    participant GH as GitHub API

    App->>SDK: new CopilotClient()
    Note over SDK: Locates CLI binary

    App->>SDK: createSession()
    SDK->>CLI: Spawn process (stdio)
    CLI->>CLI: Load credentials from keychain
    CLI->>GH: Authenticate
    GH-->>CLI: ✅ Valid session
    CLI-->>SDK: Session created
    SDK-->>App: Session ready

    App->>SDK: sendAndWait("Hello!")
    SDK->>CLI: JSON-RPC request
    CLI->>GH: Model API call
    GH-->>CLI: Response
    CLI-->>SDK: JSON-RPC response
    SDK-->>App: Response data

Configuration Options

While defaults work great, you can customize the local setup:

const client = new CopilotClient({
    // Override CLI location (default: bundled with @github/copilot)
    cliPath: "/usr/local/bin/copilot",

    // Set log level for debugging
    logLevel: "debug",

    // Pass extra CLI arguments
    cliArgs: ["--disable-telemetry"],

    // Set working directory
    cwd: "/path/to/project",

    // Auto-restart CLI if it crashes (default: true)
    autoRestart: true,
});

Using Environment Variables

Instead of the keychain, you can authenticate via environment variables. This is useful for CI or when you don't want interactive login.

# Set one of these (in priority order):
export COPILOT_GITHUB_TOKEN="gho_xxxx"   # Recommended
export GH_TOKEN="gho_xxxx"               # GitHub CLI compatible
export GITHUB_TOKEN="gho_xxxx"           # GitHub Actions compatible

The SDK picks these up automatically — no code changes needed.

Managing Sessions

With the local CLI, sessions default to ephemeral. To create resumable sessions, provide your own session ID:

// Create a named session
const session = await client.createSession({
    sessionId: "my-project-analysis",
    model: "gpt-4.1",
});

// Later, resume it
const resumed = await client.resumeSession("my-project-analysis");

Session state is stored locally at ~/.copilot/session-state/{sessionId}/.

Limitations

When to Move On

If you need any of these, it's time to pick a more advanced setup:

Next Steps

• Getting Started tutorial — Build a complete interactive app
• Authentication docs — All auth methods in detail
• Session Persistence — Advanced session management