Referência programática da CLI do GitHub Copilot

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

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

Para ver uma lista completa das opções disponíveis, consulte Referência de comandos da CLI do 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 CLI do Copilot de forma programática.

          `--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 | Exporte a transcrição da sessão para um arquivo de markdown após a conclusão de forma não interativa (como padrão para ./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 gist do GitHub 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 .

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.

          **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 subdomínio GitHub (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. |

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 CLI do Copilot, use o comando copilot help environment em seu terminal.

Escolhendo um modelo

Quando você envia um prompt para CLI do Copilot no 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/config.json (ou $COPILOT_HOME/.copilot/config.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",
  "reasoning_effort": "low"
}

{
  "model": "gpt-5.3-codex",
  "reasoning_effort": "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 --model de linha de comando.
• A variável de ambiente COPILOT_MODEL.
• A chave model no arquivo de configuração (~/.copilot/config.json ou $COPILOT_HOME/.copilot/config.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 CLI do GitHub Copilot.

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

•         [AUTOTITLE](/copilot/how-tos/copilot-cli)
  

•         [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference)
  

•         [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference)