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.

Usando assisted permissions

Em uma execução não interativa, não há ninguém disponível para responder aos prompts de aprovação. Sem nenhuma opção de permissão, as solicitações que precisam de aprovação são negadas e Copilot , muitas vezes, não podem concluir a tarefa. Com --allow-all-tools, você concede permissões amplas para ferramentas sem uma revisão de segurança do modelo.

A --assisted-approval opção é o meio termo. Uma revisão de segurança pode avaliar solicitações elegíveis que ainda não foram resolvidas pelas permissões existentes:

• Se a revisão julgar a solicitação segura, ela será aprovada automaticamente e Copilot continuará.
• Se a revisão exigir sua aprovação, a solicitação será negada e o motivo será passado de volta para Copilot, para que possa tentar uma abordagem diferente para concluir a tarefa.

As regras de negação existentes, os requisitos de aprovação obrigatória e as proteções de sandbox ainda se aplicam. Solicitações que ainda exigem sua aprovação são negadas em execuções não interativas.

Para obter mais informações sobre como a revisão de segurança funciona e qual modelo é usado, consulte Permitindo a execução de comandos seguros sem aprovação manual.

copilot -p "Fix the failing tests" --assisted-approval

copilot -p "Fix the failing tests" --assisted-approval

Você pode definir a COPILOT_ASSISTED_APPROVAL variável de ambiente para true , em vez de usar a opção. Isso é útil em ambientes automatizados em que você não pode alterar facilmente o comando executado.

Coisas que devem ser observadas

• A opção só é válida para execuções não interativas. São execuções que usam -p ou --prompt, e execuções em um ambiente sem terminal anexado, como um fluxo de trabalho de CI/CD. Se você usar --assisted-approval ao iniciar uma sessão interativa, a CLI sairá com um erro.

• Substitui --allow-all-tools quando habilitado com êxito. As solicitações de ferramenta usam assisted permissions em vez de aprovação geral da ferramenta. No entanto, --allow-all-paths e --allow-all-urls— incluindo quando eles são definidos por --allow-all ou --yolo— não são afetados, portanto, o acesso de arquivo e URL ainda pode ser irrestrito.

• Verifique se há um aviso indicando que a execução não deve continuar sem uma revisão de segurança. Se assisted permissions não puder ser ativado, porque as configurações da empresa o bloqueiam, por exemplo, a CLI grava um aviso para erro padrão e continua. Ele não cancela uma opção separada --allow-all-tools fornecida, portanto, as solicitações de ferramenta ainda podem ser aprovadas sem uma revisão de segurança.

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