Antigravity CLI: instalación, comandos, ajustes y actualización

¿Qué es Antigravity CLI?

Antigravity CLI es la superficie de línea de comandos para trabajar con el agente de Antigravity desde una terminal. Resulta útil si prefieres un flujo con teclado, quieres iniciar un agente en un repositorio, necesitas revisar un resultado sin abrir todo el IDE o deseas repetir un comando desde un entorno de desarrollo. CLI y los productos de escritorio están relacionados, pero no son el mismo destino de instalación ni usan necesariamente la misma etiqueta de versión.

La intención de búsqueda ayuda a elegir la página correcta. Usa esta guía cuando la pregunta mencione comandos, terminal, agy, settings.json, permisos de shell o VS Code. Usa las páginas del IDE para paneles del editor, instalación de escritorio o requisitos del sistema. Si el problema es un servidor, consulta la guía MCP; si necesitas la vista de control de misiones, consulta Agent Manager.

El comportamiento de CLI puede cambiar más rápido que un artículo estático. Por eso la documentación oficial es la fuente final para el instalador y la referencia de comandos. Los ejemplos de aquí explican el flujo y las comprobaciones, pero no prometen que todas las versiones expongan exactamente los mismos flags experimentales.

Cómo instalar Antigravity CLI

Empieza en la página oficial de instalación de CLI y evita mirrors de terceros. La página presenta una ruta de shell para macOS/Linux, una ruta de PowerShell para Windows y orientación para gestores de paquetes cuando corresponde. Un instalador de CLI no solo descarga un archivo: también debe colocar el comando agy en PATH y coincidir con el shell desde el que lo lanzarás.

Después de instalar, cierra y vuelve a abrir la terminal. Así se cargan los cambios de PATH. La misma precaución se aplica a la terminal integrada de VS Code: puede haber sido abierta antes de la instalación y conservar un entorno antiguo.

La tabla registra las formas oficiales del comando. Si la documentación cambia la URL del script, el nombre del paquete o las plataformas compatibles, usa la orden actual de la página oficial en lugar de copiar un fragmento viejo.

1. 1. Abre el instalador oficialLee los requisitos y ejecuta el comando vigente de la documentación oficial de CLI.
2. 2. Abre otra terminalInicia un shell nuevo para cargar PATH y la política del shell. En VS Code, abre también una terminal integrada nueva.
3. 3. Comprueba antes de autenticarEjecuta agy --version y agy --help. Si el shell no encuentra agy, arregla PATH o la instalación antes de depurar el agente.
4. 4. Haz una prueba pequeñaEjecuta agy en una carpeta pequeña y versionada. Así separas un error de instalación de un problema del repositorio o de permisos.

Nota de fuente oficial: este sitio no afirma tener una URL binaria estable, un tamaño de archivo ni un escaneo de seguridad propio para CLI. El CTA principal abre la documentación oficial de Google.

Primeros comandos de Antigravity CLI

El primer comando seguro es la ayuda, no una acción destructiva. Empieza con agy --help fuera de la sesión interactiva y con /help dentro de ella. Los comandos con barra controlan la sesión; los flags controlan el lanzamiento. Separar ambas superficies evita pegar un comando interactivo en PowerShell o Bash y pensar que CLI está roto.

Usa el comando más pequeño que responda a tu pregunta. /status o /usage ayudan a revisar una sesión, /agents es útil cuando hay varios agentes y /diff permite revisar cambios antes de aceptarlos. Para nuevas conversaciones o modelos, sigue la referencia oficial de la versión instalada en vez de conservar flags antiguos.

Ajustes de Antigravity CLI y settings.json

Los ajustes pueden hacer que CLI sea predecible o inesperadamente permisivo. La documentación oficial describe un archivo de usuario dentro de .gemini y un archivo de proyecto .gemini/settings.json. Usa el archivo de usuario para preferencias que deben acompañarte entre repositorios y el del proyecto para reglas que pertenecen a un espacio de trabajo concreto.

Prefiere la vista /settings o /config mientras aprendes el ámbito. Edita JSON manualmente solo después de confirmar qué archivo está activo. Un JSON válido en la carpeta equivocada parece un ajuste roto porque CLI nunca lo carga. Conserva una copia antes de cambiar permisos, sandbox o acceso fuera del workspace.

El siguiente ejemplo muestra una forma conservadora, no todos los valores predeterminados de cada versión. Consulta la referencia oficial para saber qué claves y valores acepta el build instalado, sobre todo si el campo controla shell o acceso a archivos.

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

• Primero el ámbito — Confirma si el ajuste pertenece al archivo de usuario o a .gemini/settings.json del proyecto.
• Después los permisos — Mantén las acciones de shell y escritura en modo de pregunta/revisión hasta entender el flujo.
• Sandbox con intención — El sandbox reduce riesgos, pero también puede limitar lo que las herramientas ven o ejecutan.
• Restablece un campo — Cuando algo falla, revierte el cambio mínimo y repite una prueba pequeña en lugar de borrar toda la configuración.

Iniciar Antigravity CLI desde una terminal o VS Code

CLI funciona mejor cuando el shell ya representa el entorno que quieres que use el agente: repositorio, Node.js, gestores de paquetes, credenciales y política de red. Un acceso directo de escritorio y la terminal integrada pueden heredar PATH distintos. Compara node -v, npm -v u otras herramientas desde la misma terminal que inicia agy.

En VS Code, abre la terminal integrada en la raíz del repositorio y ejecuta la misma comprobación de versión que usarías en una terminal normal. CLI no es una extensión de VS Code; es un flujo de terminal que puede usarse junto al editor. Para paneles y la experiencia completa de escritorio, utiliza el IDE.

En la primera ejecución, pide una explicación de un archivo pequeño, una revisión de diff o una función breve. No empieces otorgando acceso amplio al workspace ni ejecutando scripts no revisados.

Comprobar versión, actualizar y limitar un rollback

La página oficial de descarga muestra Antigravity CLI v1.1.9 por separado de las etiquetas de escritorio Antigravity 2.0 y Antigravity IDE. No uses una versión del escritorio como prueba de que CLI está actualizada. Registra agy --version, la fecha y la fuente oficial cuando informes de un problema.

Para actualizar, vuelve a la documentación oficial de instalación y usa el comando vigente para tu plataforma. Después abre otra terminal y ejecuta agy --version. Si no cambia, revisa un segundo binario anterior en PATH, una terminal antigua o una instalación administrada por la organización.

Este sitio conserva páginas antiguas del escritorio como archivo histórico. No significan que v2.2.1 sea la versión actual. Para archivos de escritorio actuales usa la página oficial de Google; para CLI usa la documentación oficial de CLI.

Comprobaciones de seguridad y permisos

Un agente CLI puede inspeccionar un repositorio, llamar a herramientas locales y proponer o ejecutar cambios. El flujo más seguro mantiene los permisos revisables, empieza en una carpeta desechable o versionada y exige entender cada comando antes de ejecutarlo. Un comando copiado de un foro no es seguro solo por aparecer en un bloque de terminal.

Si activas acceso fuera del workspace, ejecución amplia de shell o aprobaciones automáticas, documenta el motivo y cuándo debes desactivarlo. Para las decisiones de aprobación, la guía de seguridad Auto Accept es un complemento más adecuado que esta página de instalación CLI.

• Mantén shell y escritura en modo de pregunta/revisión durante la primera prueba.
• No pegues tokens, claves privadas, cookies ni credenciales de producción en los prompts.
• Revisa /diff o el artefacto generado antes de aceptar cambios.
• Usa una carpeta de prueba para separar errores de cuenta o servicio de errores del repositorio.
• Si un script solicita privilegios elevados, verifica primero la fuente oficial y su efecto exacto.

Solución de problemas de Antigravity CLI

Relaciona el arreglo con la capa que falló. Reinstalar no suele ser la primera respuesta si el problema real es PATH, ámbito de settings, cuenta o política del shell.

agy no se reconoce o command not found

Abre una terminal nueva, vuelve a ejecutar el instalador oficial solo si hace falta y revisa qué ejecutable resuelve el shell. En Windows compara PATH de PowerShell con PATH de VS Code; en macOS/Linux revisa el perfil que actualizó el instalador.

CLI inicia pero no puede usar una herramienta

Prueba una tarea de lectura en un workspace pequeño, revisa permisos y confirma que la herramienta está instalada en el mismo entorno. Si el fallo es un servidor MCP, pasa a la guía MCP en lugar de mezclar dos intenciones.

settings.json no parece hacer nada

Comprueba el ámbito y la sintaxis JSON. Cambia un solo campo, reinicia la sesión y verifica con /config o /settings.

Funciona en una terminal pero no en VS Code

Compara carpeta, PATH, shell, Node.js, proxy y variables de entorno. Reinicia VS Code después de instalar CLI. Si solo falla un repositorio, revisa settings del workspace y MCP.

La actualización sigue mostrando la versión antigua

Ejecuta agy --version desde un shell nuevo y revisa el ejecutable resuelto. Un terminal antiguo, una instalación duplicada o un PATH anterior pueden ocultar una actualización correcta.