A beginner’s guide to Unity CLI and the Pipeline package

Recientemente lanzamos la interfaz de línea de comandos de Unity CLI ) y la respuesta ha sido abrumadoramente positiva, con cada vez más casos de uso inspiradores. Sin embargo, si, como muchos otros, las herramientas de línea de comandos te resultan un poco intimidantes, te sientes más diseñador que programador o simplemente no has tenido tiempo de experimentar con ellas, esta guía está diseñada para ti.

¿Qué es la interfaz de línea de comandos de Unity ?

Una de las mayores fortalezas del editor de Unity es su GUI), que facilita la gestión visual de proyectos complejos. Inspeccionar un prefab, ajustar los valores de los materiales, ejecutar pruebas, generar la iluminación o localizar errores de la consola son tareas que se pueden realizar con tan solo unos clics del ratón en el Editor. Este flujo de trabajo ha servido a los usuarios durante casi dos décadas y se ha convertido en el cuello de botella para las tareas repetitivas, la automatización y los flujos de trabajo impulsados ​​por IA (agentes). Un agente de IA puede navegar mediante clics e interfaces exclusivamente visuales, pero esto requiere una capa adicional de interpretación visual, no nativa, que ralentiza el proceso y añade una sobrecarga innecesaria, lo que consume rápidamente los tokens.

Aquí es donde entran en juego la nueva interfaz de línea de comandos de Unity y el paquete experimental Unity Pipeline.

La CLI de Unity es, como su nombre indica, una interfaz de línea de comandos para administrar Unity. Debido a que no tiene interfaz gráfica de usuario, es excepcionalmente adecuada para la automatización y los flujos de trabajo basados ​​en agentes. Funciona como un binario (aplicación) autónomo que incluye todo lo necesario para ejecutarse, administrarse e interactuar con Unity. En otras palabras, puedes ejecutar comandos desde la terminal que se comunica directamente con Unity, reemplazando la capa de clics del ratón y flujos de trabajo completos en el Hub o el Editor.

Nota: Constantemente se añaden nuevas funciones y mejoras. En el momento de redactar este texto, la versión 1.0.0-beta.6 de Unity CLI combinada con la versión 0.5.0-exp.1 del paquete com.unity.pipeline y Unity 6000.6.0b9 es la configuración más actualizada. Si encuentra algún problema, consulte la documentación de Unity CLI: https://docs.unity.com/en-us/unity-cli/use-unity-cli

Cómo funcionan conjuntamente la interfaz de línea de comandos (CLI) de Unity y el paquete Pipeline.

Si bien el binario independiente de Unity CLI se encarga de la configuración de su entorno (como la instalación de editores, módulos y la gestión de licencias), el verdadero valor reside en combinarlo con el paquete Unity Pipeline ( com.unity.pipeline ).

Este paquete de Unity Pipeline convierte esencialmente tu editor en ejecución en un servidor HTTP local. Dado que el editor permanece abierto en segundo plano, las escenas cargadas y la base de datos de recursos se mantienen "activas" en la memoria del sistema. Al mantener todo precargado, se evita por completo la frustrante sobrecarga de arranque que supone iniciar el motor desde cero. Ahora, tu terminal (o un agente de IA) puede controlar el Editor al instante para ejecutar pruebas, cargar escenas o modificar GameObjects.

El sistema también gestiona el conocido cuello de botella de la recarga de dominio. Antes del paquete Pipeline, cada vez que usted o su agente de IA realizaban cambios directos en un script de C# en el disco, tenían que esperar a que Unity reconstruyera el proyecto y recargara el dominio. Algunas acciones incluso requerirían que te concentraras o hicieras clic en algo en el Editor antes de poder continuar.

Pero el servidor local del paquete Pipeline gestiona ese proceso de compilación de forma completamente asíncrona. La conexión se mantiene estable y activa durante toda la compilación, lo que garantiza que su sesión de terminal nunca se interrumpa ni caduque mientras el editor se recarga en segundo plano.

Las cosas se vuelven aún más rápidas cuando se ejecuta código dinámicamente mediante el comando eval . En este caso, el paquete Pipeline del Editor actúa como un traductor instantáneo, compilando el fragmento de código C# sobre la marcha y colocándolo directamente en el hilo principal de Unity. Debido a que esta ejecución dinámica es totalmente autónoma, omite por completo el proceso de recompilación de todo el proyecto y de recarga del dominio. Te ahorras por completo la tediosa espera y obtienes tus resultados en milisegundos.

Esto significa que tus scripts de automatización de alto rendimiento no se bloquearán ni perderán la conexión solo porque se esté compilando un proyecto masivo en segundo plano, mientras que tus comandos rápidos de terminal seguirán ejecutándose con una latencia prácticamente nula. Obtienes estabilidad y velocidad en la misma herramienta.

Migración de MCP a la CLI de Unity

Quizás te estés preguntando: "¿Qué hay del servidor oficial del Protocolo de Contexto de Modelos (MCP) de Unity ?". ¿Por qué no debería simplemente usar o quedarme con eso?

En resumen, no vamos a dejar de dar soporte a MCP. Sin embargo, la interfaz de línea de comandos (CLI) de Unity y el paquete Pipeline manejan los mismos casos de uso que MCP, e incluso más, pero lo hacen mucho mejor y más rápido.

La respuesta más extensa se reduce a la arquitectura. Las configuraciones tradicionales de MCP requieren un cliente activo (como Claude Desktop o Cursor) que actúe como traductor entre su agente de IA y Unity. Pero los agentes modernos, nativos de la terminal, como Claude Code, ya son increíblemente buenos ejecutando comandos estándar de la shell directamente. Al utilizar comandos de línea de comandos directos como `unity command` o `unity eval` , se evita por completo la complejidad de configurar y mantener un servidor MCP. Tu agente puede comunicarse directamente con Unity a través de un servidor HTTP local unificado y ultrarrápido. Esto significa que escribirás configuraciones más limpias, dedicarás menos tiempo a depurar los sockets de conexión y podrás dejar que tu IA funcione a la velocidad pura y nativa de la terminal.

Además, el servidor MCP heredado se ejecutaba directamente dentro del proceso del Editor como un paquete C#. Esto significaba que el propio puente de conexión estaba vinculado al hilo principal y al espacio de memoria de Unity. En el momento en que se compilaba el código o se activaba una recarga del dominio, Unity vaciaba su memoria, lo que con frecuencia provocaba que el socket de conexión se cayera, generara excepciones null o detuviera el agente a mitad del bucle.

El paquete actual com.unity.pipeline también es un paquete C# que se ejecuta dentro del Editor, pero expone un servidor HTTP y una API REST (no un puente de sockets), por lo que es más resistente a las recargas de dominio. Debido a que este servidor local procesa los comandos de forma asíncrona, su conexión de terminal permanece completamente estable y activa incluso durante compilaciones complejas y recargas de dominio.

En resumen, al pasarse a la interfaz de línea de comandos de Unity , se evitan por completo las desconexiones y el desperdicio de tokens. Por último, la CLI también ofrece un modo MCP si tiene un caso de uso específico para el que desea utilizar MCP.

Instalación del paquete CLI y Pipeline

En las versiones más recientes, la instalación de los paquetes CLI y Pipeline se realiza automáticamente con Unity Hub . En el momento de escribir este artículo, existen varias formas de instalar Unity CLI, así que asegúrese de consultar la documentación para obtener la información más reciente.

Si por alguna razón aún no lo tiene instalado, la forma más sencilla es utilizar comandos de terminal para el proceso de instalación. Puedes ver el vídeo o seguir las instrucciones que aparecen a continuación.

Para instalar la CLI de Unity , solo tienes que ejecutar los siguientes comandos desde tu terminal, dependiendo de la plataforma que estés utilizando:

# macOS o Linux

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

# Windows

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

El siguiente paso es instalar el paquete Unity Pipeline:

Instalación de canalización de Unity

Una vez instalados ambos, puedes comprobar si funcionan correctamente.

Verificación de las instalaciones

Para confirmar la instalación, simplemente ejecute el siguiente comando:

estado de unidad

Debería devolver algo como esto:

Editor de Unity (puerto 7800): readyProject: /Users/thomaskr/Github/UnityProjects/MyAwesomeProjectVersion: 6000.6.0b7PID: 85009

Si ve el estado "listo" junto a la primera línea, significa que el editor está activo y accesible. También confirma en qué puerto se encuentra el editor, la ruta del proyecto, la versión del editor y un identificador de proceso (PID).

A continuación, para asegurarte de que tu acceso ha sido autenticado, ejecuta el siguiente comando:

Inicio de sesión de autenticación de Unity

Esto abrirá tu navegador para iniciar sesión mediante OAuth en tu cuenta de Unity . Una vez que te autenticas, la interfaz de línea de comandos (CLI) almacena tus credenciales en el llavero del sistema para que los comandos futuros que necesiten autenticación (como `unity projects list`, `unity build`, `unity license`, `unity cloud` ) funcionen automáticamente sin necesidad de volver a solicitarlas.

Ejecutando algunos comandos básicos

Una vez instalados el paquete CLI y Pipeline, es hora de probar algunos comandos más. Comencemos con el comando unity --help , que te ofrece una descripción general rápida de todo lo que puedes hacer.

unidad --ayuda

El comando unity --help te proporciona una lista de todos los comandos básicos disponibles, junto con una descripción general y las opciones disponibles para cada uno.

Puede que al principio la cantidad de opciones resulte un poco abrumadora, pero la sintaxis de la interfaz de línea de comandos sigue un patrón muy lógico y coherente.

Usemos un comando que acabamos de usar como ejemplo, pero esta vez con una opción:

inicio de sesión de autenticación de unidad --no interactivo

De izquierda a derecha:

• Unity activa la interfaz de línea de comandos de Unity y, por lo tanto, es el comando principal.
• auth login son los subcomandos. Puedes considerarlos como verbos que le indican al programa principal exactamente qué acción debe realizar. Aquí, auth dirige la interfaz de línea de comandos al sistema de autenticación, y login le indica que inicie sesión.
• --no interactivo es la opción. Piensa en las opciones como si fueran parámetros. Son modificadores que le indican al comando cómo debe comportarse. En este caso, le indica a la interfaz de línea de comandos (CLI) que inicie sesión directamente a través de la terminal en lugar de abrir una ventana del navegador. Las opciones también se denominan a veces "banderas" cuando se utilizan en el contexto de opciones de encendido/apagado.

También existe un atajo de una sola letra diseñado para escribir rápidamente en tu flujo de trabajo diario en la terminal.

Volviendo a nuestra opción de ayuda ( --help ), en lugar de ejecutar unity --help también puedes usar unity -h , que te darán la misma respuesta.

unidad --ayuda # Versión larga (legibilidad mejorada) unity -h # Versión corta (más rápida en el día a día)

Las banderas cortas usan un guion simple (-) y están diseñadas como un atajo, mientras que las banderas largas usan un guion doble (--) y son las descripciones equivalentes de palabras completas diseñadas para facilitar la lectura.

El comando --help es la herramienta más importante de tu conjunto de herramientas; puedes agregarlo a prácticamente cualquier nivel de un comando anidado para obtener documentación rápida. Aquí tenéis algunos ejemplos del comando de autenticación que acabamos de ver:

# Ayuda para comandos de autenticación

unity auth --help

# Ayuda específica para el comando login

unity auth login --help

Cada pantalla de ayuda mostrará al instante exactamente qué hace el comando, qué opciones están disponibles y qué argumentos espera. En caso de duda, ¡pregunta directamente al comando!

Probemos con los comandos releases como otro ejemplo:

Lanzamientos de Unity

Esto me proporciona una buena visión general de todas las versiones disponibles para Unity en el momento de escribir esto.

Ahora agreguemos la opción --help :

Unity lanza --ayuda

El comando `unity releases --help` te ofrece una explicación de todas las opciones que puedes añadir para acotar tu búsqueda de versiones de Unity .

Por ejemplo, en el momento de escribir esto, estamos usando una versión beta de Unity 6.6b7 y queremos instalar la última versión beta. Podemos usar el comando básico de instalación de Unity , que nos proporcionará una interfaz visual sencilla donde podremos elegir la versión que deseemos.

Instalación de Unity

Seleccionemos la versión b9, que iniciará el instalador en segundo plano (y tardará unos minutos en completarse).

En lugar de usar el asistente de instalación, también puede usar el comando --help para obtener una descripción general de todos los comandos:

unity install --help

Esto te da una visión general que se ve así:

En la lista, puedes ver que puedes pasar como argumento la versión de Unity que deseas instalar. Esto significa que si tuviera una versión específica que quisiera instalar, podría hacerlo con un solo comando usando:

#Simplemente reemplaza la versión con la que quieras usar

Unity instala la versión 6000.5.9f1

Mientras tanto, nuestra nueva versión del editor ya está instalada, así que ahora necesitamos actualizar el proyecto. Para ello, añade la versión específica en la que deseas abrir el proyecto. Esto sería lo mismo que si entraras al Hub y eligieras otra versión del Editor para abrirla por proyecto y así activar la actualización del proyecto.

unity abierto --versión 6000.6.0b9

Como ya hemos mencionado, el paquete Pipeline abre un enorme conjunto de herramientas que contiene prácticamente todo lo que se puede hacer dentro del Editor de Unity (y con nuevos comandos que se añaden constantemente a medida que la versión beta madura).

Si quieres ver qué comandos están disponibles en tu proyecto actual, ejecuta:

lista de unidad

Este comando proporciona una tabla de alto nivel que muestra el nombre, el grupo y una breve descripción de cada comando. Funciona de maravilla como punto de partida para explorar rápidamente los cientos de comandos integrados, como eval , add_animator_layer , build y find_assets .

Cuando necesites saber exactamente cómo formatear tus entradas. Puedes correr:

comando de unidad

Al ejecutar esto sin argumentos, obtendrá el "plano" detallado de los comandos de Unity con documentación para cada comando registrado, incluidas las opciones (los indicadores y tipos de datos exactos que espera el comando).

Ambos comandos se comunican con el mismo proceso del Editor conectado, pero devuelven diferentes niveles de detalle. A medida que empieces a crear scripts de automatización personalizados o a configurar flujos de trabajo basados ​​en agentes que controlan Unity internamente, el comando `unity` se convertirá rápidamente en tu herramienta de consulta más utilizada para estructurar llamadas automatizadas y claras.

Finalmente, vamos a concluir analizando el comando eval y cómo ejecutar una prueba simple de Debug.Log ( "Hola Mundo" ) dentro de nuestra consola de Unity . eval es un comando del paquete Pipeline (y posiblemente el más interesante de los más de 140 comandos integrados) que compila y ejecuta dinámicamente código C# en el proceso del Editor. Intenta ejecutar el siguiente comando:

Comando de Unity eval --code 'Debug.Log("hola desde la CLI de Unity");'

Esto te da el siguiente resultado donde el JSON devuelve "éxito": verdadero si funcionó.

En el editor, ahora puede verificar que esto ha funcionado correctamente en la ventana de la consola .

Analicemos el comando:

Comando de Unity eval --code 'Debug.Log("hola desde la CLI de Unity");'

Leyendo de izquierda a derecha:

1. Unity ejecuta la herramienta CLI de Unity .
2. El comando es el subcomando que le indica que "se comunique con un editor conectado".
3. eval es un subcomando que dice "evalúa (ejecuta) algún código por mí".
4. --code es una opción (o indicador) que dice "aquí viene el código que se va a ejecutar".
5. 'Debug.Log("hola desde unity cli");' es el valor de --code ; el código real a ejecutar.

Conectando el LLM

Familiarizarse con algunos comandos básicos puede ayudar a agilizar algunas de las tareas de mantenimiento de las instalaciones de Unity , pero donde realmente destaca es cuando se empieza a automatizar e integrar los flujos de trabajo de los agentes.

Con Unity CLI y el paquete Pipeline, puedes conectar el agente que prefieras. Esto significa que, tanto si utilizas Claude, Codex, Copilot o modelos locales, etc., la interfaz de línea de comandos (CLI) está diseñada para integrarse con tu configuración preferida y debería conectarse sin necesidad de ninguna configuración adicional.

Simplemente abre una terminal, navega (usando cd) directamente al directorio de tu proyecto Unity e inicia el agente ingresando “claude” (o el comando de tu agente). Puedes confirmar que estás conectado simplemente preguntándole al agente algo parecido a lo siguiente:

Ejecuta el comando "unity" en una consola bash y dime qué puede hacer, y luego prueba un comando simple "eval".

Conectando el LLM mediante MCP

Unity ha dejado de dar soporte al servidor MCP integrado en el editor, que se encontraba en el paquete com.unity.ai.assistant . Ha sido reemplazado por el servidor MCP integrado de Unity CLI ( unity mcp ), que funciona gracias al paquete Unity Pipeline. Utiliza el mismo protocolo, por lo que los clientes se conectan sin problemas. El modo MCP sigue siendo totalmente compatible con los agentes que no pueden ejecutar comandos de shell arbitrarios o que tienen dificultades con la composición de la línea de comandos.

Para usar MCP, ejecute el siguiente comando:

Unity MCP configurar

Este comando inyecta automáticamente la configuración directamente en los ajustes de su agente. Para comprobar si su LLM está conectado, realice una pequeña prueba indicándole a su herramienta LLM que ejecute algo similar a lo siguiente:

Quiero que crees un cubo de 2 × 2 × 2 en el centro de la escena que tengo abierta actualmente. Luego, crea un script que lo haga girar continuamente alrededor de los tres ejes a 45 grados por segundo.

Esto fue lo que respondió Claude Code:

Una vez finalizado, debería entrar en modo de reproducción y ejecutar la escena para que puedas verificar que el cubo gira correctamente.

Amplíalo con tus propios comandos personalizados.

El conjunto de herramientas integradas de la interfaz de línea de comandos (CLI) cubre todos los aspectos básicos, como activar o desactivar el modo de reproducción, recompilar y ejecutar pruebas unitarias. Sin embargo, el verdadero poder de esta arquitectura reside en su extensibilidad. Puedes escribir fácilmente comandos personalizados para proporcionar a tus agentes de IA un contexto adaptado y específico del proyecto, así como herramientas únicas creadas exclusivamente para tu juego.

Crear un comando personalizado es muy sencillo. Lo único que tienes que hacer es escribir un método estático estándar de C# y decorarlo con los atributos [CliCommand] y [CliArg] .

El paquete Pipeline detecta automáticamente estos atributos durante la compilación, lo que significa que no requiere configuración manual ni archivos de registro. Cuando ejecutas un comando de Unity sin argumentos, la interfaz de línea de comandos (CLI) muestra dinámicamente todos los comandos personalizados disponibles junto con los comandos integrados.

Nota: El atributo [CliCommand] permite descubrir y ejecutar comandos a través de la interfaz de línea de comandos (CLI). Para la ejecución parametrizada, se llama al método directamente utilizando el comando `eval` de Unity con sintaxis de C#, en lugar de pasar indicadores al estilo de la interfaz de línea de comandos (CLI).

Veamos un ejemplo sencillo de un comando personalizado "Hola Mundo" en acción.

Crea un nuevo script de C# llamado HelloWorldCommand.cs . Asegúrese de que la clase y el método sean estáticos e incluya el espacio de nombres Unity.Pipeline.Commands :

utilizando UnityEngine;

usando Unity.Pipeline.Commands;

clase estática pública HelloWorldCommand

{

[CliCommand("hello-world", "Un comando simple para decir hola mundo")]

public static void SayHello()

{

Debug.Log("¡Hola, mundo! Este es un comando CLI personalizado.");

}

}

Para ejecutar tu nuevo comando, abre tu terminal y ejecuta el siguiente comando:

comando unity hola-mundo

La terminal debería verse algo así:

Y el registro de tu consola debería verse así:

También podrías ampliar la función si necesitas pasar parámetros usando el atributo [CliArg] .

utilizando UnityEngine;

usando Unity.Pipeline.Commands;

clase estática pública HelloWorldCommand

{

[CliCommand("hello-world", "Un comando simple para decir hola mundo")]

público estático void SayHello(

[CliArg("nombre", "A quién saludar")] cadena nombre)

{

Debug.Log($"¡Hola, {nombre}! Este es un comando CLI personalizado.");

}

}

Para ejecutar tu nuevo comando, abre tu terminal y ejecuta:

unity command hello-world --name "thomas"

Instalación del complemento Unity Agent

Unity también ofrece un plugin oficial para el desarrollo de juegos , que en el momento de escribir este artículo está disponible para Claude Code, Codex y Grok. Ofrece habilidades seleccionadas para el desarrollo de juegos y la optimización del rendimiento. Una vez instaladas, las habilidades se cargan automáticamente cuando trabajas en un proyecto de Unity en cualquiera de las opciones mencionadas anteriormente. Para instalarlo en Claude, simplemente ejecute este comando:

Claude Plugin Marketplace Añadir Unity-Technologies/unity-agent-plugin

github.com/Unity-Technologies/unity-agent-plugin

Otro consejo rápido si eres usuario de Claude Code y estás comenzando un nuevo proyecto es ejecutar la fase de inicialización, que configura Claude con el contexto básico de tu proyecto mediante la creación de un archivo claude.md . Se trata de un archivo Markdown que reside en la raíz de la carpeta de tu proyecto y que Claude Code lee al inicio de cada sesión.

/init # Ejecuta este comando dentro del código de Claude

De esa forma, puedes usarlo para informarle a Claude sobre tu conjunto de tecnologías preferido, como por ejemplo, si prefieres uGUI en lugar de UI Toolkit como interfaz de usuario, el nuevo Input System en lugar del antiguo administrador de entrada, etc. También podría utilizarse para decisiones de arquitectura, como usar un patrón de localizador de servicios en lugar de singletons, MVP para el diseño de la interfaz de usuario, etc.

Si bien Claude también crea una memoria automática a medida que funciona, guardando los aprendizajes entre sesiones sin que usted escriba nada, el archivo Claude.md ayuda a guiar la dirección general del proyecto específico.

A medida que avances en el proceso, puedes considerar agregar instrucciones más personalizadas, como tu guía de estilo de código. Escribí un artículo sobre cómo funciona esto para las instrucciones personalizadas en el asistente de IA, pero los principios son exactamente los mismos para Claude Code si estás interesado en aprender más.

¿Cuál es el siguiente paso?

Esperamos que esta introducción les haya resultado útil para comenzar. Si te interesa optimizar aún más tu flujo de trabajo agencial, consulta el artículo sobre cómo configurar instrucciones personalizadas para tu LLM, incluyendo la definición de una guía de estilo de código Unity C# .

Mira el video aquí:

Interfaz de línea de comandos (CLI) de Unity