referência programática do GitHub Copilot CLI

Além de executar Copilot CLI interativamente, você também pode passar um prompt diretamente para a CLI em um único comando, sem inserir uma sessão interativa. Isso permite que você use Copilot de forma programática em scripts, pipelines de CI/CD e workflows de automação. Para obter mais informações, consulte Executando GitHub Copilot CLI programaticamente.

Este artigo descreve as opções de linha de comando e as variáveis de ambiente que são particularmente relevantes ao executar Copilot CLI programaticamente.

Para ver uma lista completa das opções disponíveis, consulte referência de comando da CLI GitHub Copilot ou insira o seguinte comando em seu terminal:

Shell

copilot help

copilot help

Opções de linha de comando

Há várias opções de linha de comando que são particularmente úteis ao executar Copilot CLI programaticamente.

Opção	Descrição
`-p PROMPT`	Execute um comando no modo não interativo. A CLI executa o prompt e sai quando terminar a execução.
`-s`	Suprimir estatísticas e decoração, exibindo apenas a resposta do agente. Ideal para direcionar a saída em scripts.
`--add-dir=DIRECTORY`	Adicione um diretório à lista de caminhos permitidos. Isso pode ser usado várias vezes para adicionar vários diretórios. Útil quando o agente precisa ler/gravar fora do diretório de trabalho atual.
`--agent=AGENT`	Especifique um custom agent a ser usado.
`--allow-all`(ou `--yolo`)	Permitir todas as permissões da CLI. Equivalente a `--allow-all-tools --allow-all-paths --allow-all-urls`.
`--allow-all-paths`	Desabilite totalmente a verificação do caminho do arquivo. Alternativa mais simples para `--add-dir` quando as restrições de caminho não são necessárias.
`--allow-all-tools`	Permitir que cada ferramenta seja executada sem permissão explícita para cada ferramenta.
`--allow-all-urls`	Permitir o acesso a todas as URLs sem permissão explícita para cada URL.
`--allow-tool=TOOL ...`	Conceda permissão seletivamente para uma ferramenta específica. Para várias ferramentas, use uma lista entre aspas e separada por vírgulas.
`--allow-url=URL ...`	Permitir que o agente busque uma URL ou domínio específico. Útil quando um fluxo de trabalho precisa de acesso à Web para pontos de extremidade conhecidos. Para várias URLs, use uma lista entre aspas e separada por vírgulas.
`--deny-tool=TOOL ...`	Negar uma ferramenta específica. Útil para restringir o que o agente pode fazer em um fluxo de trabalho bloqueado. Para várias ferramentas, use uma lista entre aspas e separada por vírgulas.
`--model=MODEL`	Escolha o modelo de IA (por exemplo, `gpt-5.2` ou `claude-sonnet-4.6`). Útil para fixar um modelo em fluxos de trabalho reproduzíveis. Veja como escolher um modelo abaixo.
`--no-ask-user`	Evitar que o agente pause para solicitar informações adicionais do usuário.
`--secret-env-vars=VAR ...`	Uma variável de ambiente cujo valor você deseja redigir na saída. Para várias variáveis, use uma lista entre aspas e separada por vírgulas. Essencial para evitar que segredos sejam expostos em logs. Os valores nas variáveis de ambiente `GITHUB_TOKEN` e `COPILOT_GITHUB_TOKEN` são redigidos por padrão.
`--share=PATH`	Exportar a transcrição da sessão para um arquivo Markdown após a conclusão não interativa (o padrão é `./copilot-session-<ID>.md`). Útil para auditar ou arquivar o que o agente fez. Observe que as transcrições de sessão podem conter informações confidenciais.
`--share-gist`	Publique a transcrição da sessão como um GitHub gist secreto após a conclusão. Conveniente para compartilhamento de resultados da CI. Observe que as transcrições de sessão podem conter informações confidenciais.

Ferramentas para a opção `--allow-tool`

Você pode especificar vários tipos de ferramentas com a opção --allow-tool .

Tipo de ferramenta	O que controla
shell	Executando comandos de shell.
gravação	Criando ou modificando arquivos.
leitura	Lendo arquivos ou diretórios.
url	Buscando conteúdo de uma URL.
memória	Armazenando novos fatos na memória persistente do agente. Isso não afeta o uso de memórias existentes. Consulte Sobre a Memória do GitHub Copilot.
MCP-SERVER	Invocando ferramentas de um servidor MCP específico. Use o nome configurado do servidor como o identificador, por exemplo, `github`. Consulte Adicionando servidores MCP para GitHub Copilot CLI.

Filtros de ferramenta

Os tipos de ferramentas de servidor shell, write, url e MCP permitem que você especifique um filtro, entre parênteses, para controlar quais ferramentas específicas são permitidas.

Tipo de ferramenta	Exemplo	Explicação do exemplo
Shell	`shell(git:*)`	Permitir todos os subcomandos git (`git push`, `git status`etc.).
	`shell(npm test)`	Permitir o comando exato `npm test`.
escrever	`write(.github/copilot-instructions.md)`	Permitir que a CLI escreva nesse caminho específico.
	`write(README.md)`	Permitir que a CLI escreva em qualquer arquivo cujo caminho termina com `/README.md`.
url	`url(github.com)`	Permitir que a CLI acesse URLs HTTPS no github.com.
	`url(http://localhost:3000)`	Permitir que a CLI acesse o servidor de desenvolvimento local com o protocolo e a porta explícitos.
	`url(https://*.github.com)`	Permitir que a CLI acesse qualquer GitHub subdomínio (por exemplo, `api.github.com`).
	`url(https://docs.github.com/copilot/*)`	Permitir acesso à documentação Copilot, neste site.
MCP-SERVER	`github(create_issue)`	Permitir somente a ferramenta `create_issue` do servidor `github` MCP.

Observação

Os curingas são permitidos apenas para shell para corresponder a todos os subcomandos de uma ferramenta específica e para url no início do nome do host para corresponder a qualquer subdomínio ou no final de um caminho para corresponder a qualquer sufixo de caminho — conforme mostrado na tabela anterior.

Variáveis de ambiente

Você pode usar variáveis de ambiente para configurar vários aspectos do comportamento da CLI ao executar programaticamente. Isso é particularmente útil para definir a configuração em fluxos de trabalho de CI/CD ou em outros ambientes automatizados em que talvez você não queira especificar determinadas opções diretamente na linha de comando.

Variable	Descrição
`COPILOT_ALLOW_ALL`	Definir `true` para permissões completas
`COPILOT_MODEL`	Definir o modelo (por exemplo, `gpt-5.2`, `claude-sonnet-4.5`)
`COPILOT_HOME`	Defina o diretório para o arquivo de configuração da CLI (`~/.copilot` por padrão)
`COPILOT_GITHUB_TOKEN`	Token de autenticação (precedência mais alta)
`GH_TOKEN`	Token de autenticação (segunda precedência)
`GITHUB_TOKEN`	Token de autenticação (terceira precedência)

Para obter detalhes completos das variáveis de ambiente para Copilot CLI, use o comando copilot help environment em seu terminal.

Escolhendo um modelo

Quando você envia um prompt no Copilot CLI modo não interativo, o modelo que a CLI usa para gerar uma resposta é mostrado na saída da resposta (se a opção -s, ou --silent, não for usada).

Você pode usar a opção --model para especificar qual modelo de IA a CLI deve usar. Isso permite que você escolha um modelo mais adequado para seu prompt, equilibrando fatores como velocidade, custo e funcionalidade.

Por exemplo, para tarefas simples, como explicar algum código ou gerar um resumo, você pode escolher um modelo rápido e de menor custo, como um modelo Claude Haiku:

Bash

copilot -p "What does this project do?" -s --model claude-haiku-4.5

copilot -p "What does this project do?" -s --model claude-haiku-4.5

Para tarefas mais complexas que exigem um raciocínio mais profundo, como depuração ou refatoração de código, você pode escolher um modelo mais poderoso, como um modelo GPT Codex.

Bash

copilot -p "Fix the race condition in the worker pool" \
  --model gpt-5.3-codex \
  --allow-tool='write, shell'

copilot -p "Fix the race condition in the worker pool" \
  --model gpt-5.3-codex \
  --allow-tool='write, shell'

Observação

Você pode encontrar as cadeias de caracteres de modelo para todos os modelos disponíveis na descrição da opção --model ao entrar copilot help no terminal.

Como alternativa, você pode definir a COPILOT_MODEL variável de ambiente para especificar um modelo durante a sessão do shell.

Para persistir uma seleção de modelo entre sessões de shell, você pode definir a model chave no arquivo de configuração da CLI. Esse arquivo está localizado em ~/.copilot/settings.json (ou $COPILOT_HOME/settings.json se você definiu a variável de COPILOT_HOME ambiente). Alguns modelos também permitem que você defina um nível de esforço de raciocínio, que controla quanto tempo o modelo passa pensando antes de responder.

JSON

{
  "model": "gpt-5.3-codex",
  "effortLevel": "low"
}

{
  "model": "gpt-5.3-codex",
  "effortLevel": "low"
}

Dica

A maneira mais fácil de definir um modelo persistente no arquivo de configuração é com o /model comando barra em uma sessão interativa. A escolha que você faz com esse comando é gravada no arquivo de configuração.

Precedência do modelo

Ao determinar qual modelo usar para um determinado prompt, a CLI verifica se há especificações de modelo na seguinte ordem de precedência (da mais alta para a mais baixa):

Onde um agente personalizado é usado: o modelo especificado na definição do agente personalizado (se houver).
A opção de linha de comando --model.
A variável de ambiente COPILOT_MODEL.
A chave model no arquivo de configuração (~/.copilot/settings.json ou $COPILOT_HOME/settings.json).
O modelo padrão da CLI.

Usando agentes personalizados

Você pode delegar o trabalho a um agente especializado usando a opção --agent . Para obter mais informações, consulte Criando e usando agentes personalizados para GitHub Copilot CLI.

Neste exemplo, o code-review agente é usado. Isso requer que um agente personalizado tenha sido criado com esse nome.

copilot -p "Review the latest commit" \
  --allow-tool='shell' \
  --agent code-review