Usando uma CLI local com o SDK do Copilot

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Conectar SDK do GitHub Copilot à CLI em que você está conectado localmente é a maneira mais rápida de começar.

          **Melhor para:** Projetos pessoais, protótipos, desenvolvimento local e aprendizado do SDK.

Como funciona

Quando você instala CLI do Copilot e entra, suas credenciais são armazenadas no conjunto de chaves do sistema. O SDK inicia automaticamente a CLI como um processo filho e usa essas credenciais armazenadas. Principais características:

• A CLI é gerada automaticamente pelo SDK, sem necessidade de instalação.
• A autenticação usa as credenciais do usuário conectado do conjunto de chaves do sistema.
• A comunicação ocorre por stdio (stdin/stdout)— nenhuma porta de rede é aberta.
• As sessões são locais para seu computador.

Início rápido

A configuração padrão não requer nenhuma opção.

Node.js/TypeScript

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

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

Python

from copilot import CopilotClient, PermissionHandler

client = CopilotClient()
await client.start()

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

await client.stop()

Go

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)

.NET

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

O SDK lida com tudo: iniciando a CLI, autenticando e gerenciando a sessão.

Como isso funciona internamente?

Para obter mais informações sobre a ordem de interação entre componentes, consulte o diagrama de sequência no github/copilot-sdkrepositório.

Opções de configuração

Embora os padrões funcionem para a maioria dos casos, você pode personalizar a configuração local:

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: ["--log-dir=/tmp/copilot-logs"],

    // Set working directory
    cwd: "/path/to/project",
});

Usando variáveis de ambiente

Em vez do conjunto de chaves, você pode autenticar por meio de variáveis de ambiente. Isso é útil para CI ou quando você não deseja entrar interativamente.

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

Substitua YOUR-GITHUB-TOKEN por um token OAuth ou válido GitHubpersonal access token . O SDK os seleciona automaticamente– nenhuma alteração de código é necessária.

Gerenciamento de sessões

Com a CLI local, as sessões são efêmeras por padrão. Para criar sessões retomáveis, forneça uma ID de sessão:

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

// Resume it in a later run
const resumed = await client.resumeSession("my-project-analysis");

O estado da sessão é armazenado localmente em ~/.copilot/session-state/SESSION-ID/, onde SESSION-ID está a ID da sessão fornecida.

Limitações

Limitation	Detalhes

          **Usuário único** | As credenciais estão vinculadas a quem entrou na CLI. |

| Somente local | A CLI é executada no mesmo computador que seu aplicativo. | | Nenhum suporte para multiusuário | Não é possível atender a vários usuários de uma instância da CLI. | | Requer entrada da CLI | O usuário deve executar copilot e autenticar primeiro. |

Próximas Etapas 

• Para enviar seu aplicativo para outros usuários, consulte Usando uma CLI agrupada com o SDK do Copilot.
• Para dar suporte a vários usuários que se conectam com suas próprias GitHub contas, consulte Usando o GitHub OAuth com o SDK do Copilot.
• Para executar o SDK em um servidor, consulte Configurando o SDK do Copilot para serviços de back-end.
• Para sua primeira mensagem e instalação, consulte Introdução ao SDK do Copilot.