{"meta":{"title":"referência programática do GitHub Copilot CLI","intro":"Encontre opções para execução CLI do Copilot programática.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/reference","title":"Referência"},{"href":"/pt/copilot/reference/copilot-cli-reference","title":"\n CLI do Copilot referência"},{"href":"/pt/copilot/reference/copilot-cli-reference/cli-programmatic-reference","title":"Referência programática da CLI"}],"documentType":"article"},"body":"# referência programática do GitHub Copilot CLI\n\nEncontre opções para execução CLI do Copilot programática.\n\nAlé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).\n\nEste 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.\n\nPara 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:\n\n```shell copy\ncopilot help\n```\n\n## Opções de linha de comando\n\nHá várias opções de linha de comando que são particularmente úteis ao executar CLI do Copilot programaticamente.\n\n| Opção | Descrição |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `-p PROMPT` | Execute um comando no modo não interativo. A CLI executa o prompt e sai quando terminar a execução. |\n| `-s` | Suprimir estatísticas e decoração, exibindo apenas a resposta do agente. Ideal para direcionar a saída em scripts. |\n| `--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. |\n| `--agent=AGENT` | Especifique um agente personalizado a ser usado. |\n| `--allow-all`(ou `--yolo`) | Permitir todas as permissões da CLI. Equivalente a `--allow-all-tools --allow-all-paths --allow-all-urls`. |\n| `--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. |\n| `--allow-all-tools` | Permitir que cada ferramenta seja executada sem permissão explícita para cada ferramenta. |\n| `--allow-all-urls` | Permitir o acesso a todas as URLs sem permissão explícita para cada URL. |\n| `--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. |\n| `--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. |\n| `--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. |\n| `--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. |\n| `--no-ask-user` | Evitar que o agente pause para solicitar informações adicionais do usuário. |\n| `--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. |\n| `--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. |\n| `--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. |\n\n## Ferramentas para a opção `--allow-tool`\n\nVocê pode especificar vários tipos de ferramentas com a opção `--allow-tool` .\n\n| Tipo de ferramenta | O que controla |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| shell | Executando comandos de shell. |\n| gravação | Criando ou modificando arquivos. |\n| leitura | Lendo arquivos ou diretórios. |\n| url | Buscando conteúdo de uma URL. |\n| 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). |\n| 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). |\n\n### Filtros de ferramenta\n\nOs 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.\n\n\n\n| Tipo de ferramenta | Exemplo | Explicação do exemplo |\n| ------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| **Shell** | `shell(git:*)` | Permitir todos os subcomandos git (`git push`, `git status`etc.). |\n| | `shell(npm test)` | Permitir o comando exato `npm test`. |\n| **escrever** | `write(.github/copilot-instructions.md)` | Permitir que a CLI escreva nesse caminho específico. |\n| | `write(README.md)` | Permitir que a CLI escreva em qualquer arquivo cujo caminho termina com `/README.md`. |\n| **url** | `url(github.com)` | Permitir que a CLI acesse URLs HTTPS no github.com. |\n| | `url(http://localhost:3000)` | Permitir que a CLI acesse o servidor de desenvolvimento local com o protocolo e a porta explícitos. |\n| | `url(https://*.github.com)` | Permitir que a CLI acesse qualquer GitHub subdomínio (por exemplo, `api.github.com`). |\n| | `url(https://docs.github.com/copilot/*)` | Permitir acesso à documentação Copilot, neste site. |\n| **MCP-SERVER** | `github(create_issue)` | Permitir somente a ferramenta `create_issue` do servidor `github` MCP. |\n\n\n\n> \\[!NOTE]\n> 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.\n\n## Variáveis de ambiente\n\nVocê 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.\n\n| Variable | Descrição |\n| ---------------------- | ---------------------------------------------------------------------------------- |\n| `COPILOT_ALLOW_ALL` | Definir `true` para permissões completas |\n| `COPILOT_MODEL` | Definir o modelo (por exemplo, `gpt-5.2`, `claude-sonnet-4.5`) |\n| `COPILOT_HOME` | Defina o diretório para o arquivo de configuração da CLI (`~/.copilot` por padrão) |\n| `COPILOT_GITHUB_TOKEN` | Token de autenticação (precedência mais alta) |\n| `GH_TOKEN` | Token de autenticação (segunda precedência) |\n| `GITHUB_TOKEN` | Token de autenticação (terceira precedência) |\n\nPara obter detalhes completos das variáveis de ambiente para CLI do Copilot, use o comando `copilot help environment` em seu terminal.\n\n## Escolhendo um modelo\n\nQuando 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).\n\nVocê 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.\n\nPor 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:\n\n```bash copy\ncopilot -p \"What does this project do?\" -s --model claude-haiku-4.5\n```\n\nPara 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.\n\n```bash copy\ncopilot -p \"Fix the race condition in the worker pool\" \\\n --model gpt-5.3-codex \\\n --allow-tool='write, shell'\n```\n\n> \\[!NOTE]\n> 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.\n\nComo alternativa, você pode definir a `COPILOT_MODEL` variável de ambiente para especificar um modelo durante a sessão do shell.\n\nPara 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.\n\n```json copy\n{\n \"model\": \"gpt-5.3-codex\",\n \"reasoning_effort\": \"low\"\n}\n```\n\n> \\[!TIP]\n> 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.\n\n### Precedência do modelo\n\nAo 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):\n\n* Onde um agente personalizado é usado: o modelo especificado na definição do agente personalizado (se houver).\n* A opção de linha de comando `--model`.\n* A variável de ambiente `COPILOT_MODEL`.\n* A chave `model` no arquivo de configuração (`~/.copilot/config.json` ou `$COPILOT_HOME/.copilot/config.json`).\n* O modelo padrão da CLI.\n\n## Usando agentes personalizados\n\nVocê 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).\n\nNeste exemplo, o `code-review` agente é usado. Isso requer que um agente personalizado tenha sido criado com esse nome.\n\n```bash\ncopilot -p \"Review the latest commit\" \\\n --allow-tool='shell' \\\n --agent code-review\n```\n\n## Leitura adicional\n\n* [CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli)\n* [referência de comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [referência de plugin da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-plugin-reference)"}