Antigravity CLI: instalação, comandos, configurações e atualização

O que é o Antigravity CLI?

O Antigravity CLI é a interface de linha de comando para trabalhar com o agente Antigravity a partir de um terminal. Ele serve para fluxos controlados pelo teclado, para iniciar um agente em um repositório ou para conferir um resultado sem abrir toda a IDE. CLI e produtos desktop são relacionados, mas têm alvos de instalação e números de versão diferentes.

Use este guia quando a pergunta envolver comandos, terminal, agy, settings.json, permissões do shell ou o terminal do VS Code. Painéis do editor e requisitos desktop ficam nos guias da IDE; servidores MCP e a interface antiga do Agent Manager têm páginas próprias.

O comportamento da CLI pode mudar mais rápido que um artigo estático. A documentação oficial é a fonte de verdade para o instalador e a referência de comandos. Os exemplos explicam o fluxo e as verificações de segurança, sem garantir flags experimentais idênticas em todas as builds.

Como instalar o Antigravity CLI

Comece pela página oficial de instalação da CLI, não por um mirror de terceiros. Ela apresenta um caminho de shell para macOS/Linux, um caminho de PowerShell para Windows e instruções de gerenciador de pacotes quando disponíveis. O instalador também precisa colocar o comando agy no PATH do shell que será usado.

Depois da instalação, feche e abra o terminal novamente. Alterações no PATH podem não aparecer em uma sessão antiga ou em um VS Code iniciado antes da instalação. Abra também um novo terminal integrado no VS Code.

A tabela registra o formato dos comandos oficiais. Se a URL do script, o nome do pacote ou as plataformas mudarem, use o comando atual da página oficial em vez de copiar um trecho antigo.

1. 1. Abrir o instalador oficialLeia os pré-requisitos e execute o comando atual da documentação oficial da CLI.
2. 2. Abrir o terminal novamenteInicie um shell novo para carregar PATH e políticas. Faça o mesmo no terminal integrado do VS Code.
3. 3. Conferir antes de autenticarExecute agy --version e agy --help. Se o comando não existir, corrija o PATH antes de investigar o agente.
4. 4. Fazer um teste pequenoUse primeiro uma pasta pequena e versionada para separar instalação de problemas de repositório ou permissão.

Nota sobre a fonte oficial: este site não afirma ter URL permanente de binário, tamanho de arquivo ou varredura de segurança para a CLI. O CTA principal abre a documentação oficial do Google.

Primeiros comandos do Antigravity CLI

O primeiro comando mais seguro é a ajuda, não uma ação destrutiva. Use agy --help fora da sessão e /help dentro de uma sessão ativa. Comandos de barra controlam a sessão; flags da CLI controlam o lançamento. Não cole um comando interativo no PowerShell ou Bash esperando que ele funcione como uma opção de inicialização.

Use /status ou /usage para conferir a sessão, /agents quando houver vários agentes e /diff antes de aceitar mudanças. Para conversa nova ou outro modelo, consulte a referência oficial atual em vez de reutilizar uma flag antiga.

Configurações do Antigravity CLI e settings.json

As configurações tornam a CLI previsível — ou permissiva de forma inesperada. A documentação oficial descreve um arquivo de usuário sob .gemini e um arquivo de projeto .gemini/settings.json. Use o arquivo de usuário para preferências gerais e o arquivo do projeto para regras que podem ser revisadas junto ao repositório.

Prefira /settings ou /config enquanto aprende o escopo. Edite JSON manualmente apenas depois de descobrir qual arquivo está ativo e mantenha um backup antes de alterar permissões, sandbox ou acesso fora do workspace. JSON válido no diretório errado não será carregado.

O exemplo abaixo mostra uma forma conservadora, não todos os padrões de cada release. Confirme chaves e valores aceitos na referência oficial, especialmente os que controlam shell e acesso a arquivos.

{"toolPermission":{"shell":"ask","fileWrite":"ask"},"enableTerminalSandbox":true,"allowNonWorkspaceAccess":false}

• Escopo primeiro — Confirme arquivo do usuário ou .gemini/settings.json do projeto antes da alteração.
• Permissões depois — Mantenha shell e fileWrite em ask ou revisão até entender o fluxo.
• Sandbox de propósito — Pode reduzir riscos, mas também mudar o que as ferramentas veem ou executam.
• Restaurar um campo — Desfaça a menor mudança e repita um teste, em vez de apagar toda a configuração.

Iniciar o Antigravity CLI no terminal ou no VS Code

A CLI funciona melhor quando o shell já representa o ambiente desejado: repositório, Node.js ou Python, gerenciadores de pacotes, credenciais, proxy e política do shell. Um atalho desktop e um terminal integrado podem herdar PATH diferente; compare as ferramentas no terminal que inicia o agy.

No VS Code, abra o terminal integrado na raiz do repositório e faça a mesma verificação de versão usada em um terminal normal. A CLI não é uma extensão do VS Code; é um fluxo de terminal que pode ser usado ao lado dele. Para painéis do editor ou experiência desktop completa, use a IDE.

No primeiro uso, peça a explicação de um arquivo pequeno ou uma revisão de diff. Não comece concedendo amplo acesso ao workspace ou executando script de instalação não verificado.

Verificação de versão, atualização e limites de rollback

A página oficial do Antigravity lista a CLI v1.1.9 separadamente do Antigravity 2.0 desktop e da Antigravity IDE. Não use uma versão desktop como prova de que a CLI está atual; registre agy --version, a data e a fonte oficial.

Para atualizar, volte à documentação oficial de instalação ou download e use o caminho da plataforma. Abra um terminal novo e execute agy --version novamente. Se a versão não mudar, confira outra instalação no PATH, terminal antigo ou instalação gerenciada pela organização.

As páginas desktop antigas deste site são arquivos históricos. Elas não dizem que v2.2.1 é atual. Para o desktop, use a página oficial do Google; para a CLI, use a documentação oficial da CLI.

Verificações de segurança e permissões

Um agente CLI pode ler um repositório, chamar ferramentas locais e propor ou executar mudanças. Mantenha permissões revisáveis, comece em uma pasta versionada e entenda cada comando antes de executá-lo. Um comando copiado de um fórum não é seguro apenas por estar em um bloco de terminal.

Se usar acesso fora do workspace, execução ampla de shell ou aprovações automáticas, registre o motivo e quando esses direitos devem ser removidos. O guia de segurança Auto Accept ajuda a decidir aprovações.

• Mantenha shell e fileWrite em ask/revisão no primeiro uso.
• Não cole tokens, chaves privadas, cookies ou credenciais de produção nos prompts.
• Revise /diff ou o resultado gerado antes de aceitar mudanças.
• Use uma pasta de teste limpa para separar erros de conta e de repositório.
• Pare quando um script pedir privilégios elevados e confirme fonte e efeito exato.

Troubleshooting do Antigravity CLI

Corrija a camada que falhou. Reinstalar raramente é a primeira resposta quando a causa é PATH, escopo de configurações, conta ou política do shell.

agy não é reconhecido

Abra um terminal novo e confira qual executável o shell resolve. No Windows compare PATH do PowerShell e do VS Code; em macOS/Linux confira o perfil atualizado pelo instalador. Não adicione um diretório mirror não verificado.

A CLI inicia, mas não usa uma ferramenta

Faça um prompt de leitura em um workspace pequeno, verifique a permissão e confirme que a ferramenta está no mesmo ambiente. Se for MCP, use o guia MCP.

settings.json não parece funcionar

Confira escopo e sintaxe JSON. Um arquivo fora do .gemini esperado pode não ser carregado. Altere um campo, reinicie a sessão e confira com /config ou /settings.

Funciona no terminal normal, mas não no VS Code

Compare diretório, PATH, shell, Node.js, proxy e variáveis de ambiente. Reinicie completamente o VS Code após instalar a CLI.

A atualização ainda mostra a versão antiga

Execute agy --version em um shell novo e examine o executável resolvido. Terminal antigo, instalação duplicada ou ordem do PATH podem esconder uma atualização bem-sucedida.