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:

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.

Execução de fluxos de trabalho dinâmicos

Use copilot workflow run WORKFLOW-NAME para executar um fluxo de trabalho dinâmico a partir de um script. Para saber mais sobre fluxos de trabalho dinâmicos, consulte Fluxos de trabalho dinâmicos.

Use --args para JSON embutido ou um @caminho de arquivo JSON prefixado. Os argumentos não são lidos da entrada padrão.

copilot workflow run WORKFLOW-NAME \
  --args @workflow-input.json \
  --silent --output-format json

copilot workflow run WORKFLOW-NAME \
  --args @workflow-input.json \
  --silent --output-format json

Configure a autenticação e conceda as permissões necessárias para a ferramenta antes de executar o comando. Opções compartilhadas, como --model, --allow-tool, --allow-urle --add-dir aplicar. O comando não exibe prompts de aprovação de permissão. Opções de prompt e modo de sessão, como -p, -i, --agent, --fleet, --autopilot, --resumee --continue não têm suporte com workflow run.

As extensões de projeto são carregadas somente de pastas confiáveis ou com consentimento explícito. Na automação, GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true permite o carregamento de extensões de projeto para essa invocação. Habilite-o apenas para o código do repositório em que você confia. Ele não concede permissões de ferramenta.

Para todas as opções específicas do fluxo de trabalho, consulte referência de comando da CLI GitHub Copilot.

Saída do fluxo de trabalho

Com --output-format jsona saída padrão usa JSONL. Quando a execução é concluída ou interrompida, o registro final tem os campos a seguir. Adicione --silent para suprimir o progresso e outros registros de eventos.

Com --result-file PATH, o arquivo contém apenas o valor retornado, como JSON. Uma execução pausada, com falha ou interrompida, não substitui um arquivo de resultado existente. Uma execução concluída que não retorna nenhum valor não grava um arquivo de resultado.

Erros e diagnósticos para execuções que não são concluídas são gravados em erro padrão, inclusive no modo silencioso. Um erro antes do início do fluxo de trabalho ou uma interrupção pode encerrar o comando sem um registro JSON final.

Códigos de saída do fluxo de trabalho

Verifique o código de saída antes de consumir um arquivo de resultado. Um arquivo de resultado anterior ainda pode existir após uma execução malsucedida. Um registro final com data.run.status definido como completed não garante que o arquivo de resultados tenha sido salvo com êxito.

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

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

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.

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.

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:

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.

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'

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.

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

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

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

Leitura adicional

• GitHub Copilot CLI
• referência de comando da CLI GitHub Copilot
• referência de plugin da CLI GitHub Copilot