# referência programática do GitHub Copilot CLI Encontre opções para execução CLI do Copilot programática. Além de executar CLI do Copilot 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 CLI do GitHub Copilot programaticamente](/pt/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically). Este artigo descreve as opções de linha de comando e as 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 comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference#command-line-options) ou insira o seguinte comando em seu terminal: ```shell copy 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 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 agente personalizado 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](#choosing-a-model) 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-.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 memória agente para GitHub Copilot](/pt/copilot/concepts/agents/copilot-memory). | | 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 CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). | ### 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. | > \[!NOTE] > 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 CLI do Copilot, use o comando `copilot help environment` em seu terminal. ## Escolhendo um modelo Quando você envia um prompt no CLI do Copilot 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 copy 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 copy copilot -p "Fix the race condition in the worker pool" \ --model gpt-5.3-codex \ --allow-tool='write, shell' ``` > \[!NOTE] > 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 copy { "model": "gpt-5.3-codex", "effortLevel": "low" } ``` > \[!TIP] > 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 CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli). Neste exemplo, o `code-review` agente é usado. Isso requer que um agente personalizado tenha sido criado com esse nome. ```bash copilot -p "Review the latest commit" \ --allow-tool='shell' \ --agent code-review ``` ## Leitura adicional * [CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli) * [referência de comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference) * [referência de plugin da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-plugin-reference)