O que é o Unity CLI

A Unity lançou uma CLI oficial que permite trabalhar com projetos Unity diretamente pelo terminal, sem precisar abrir o Unity Editor. Isso muda bastante o fluxo de trabalho para equipes que usam Unity em ambientes de CI/CD, servidores de build ou simplesmente preferem trabalhar mais pelo terminal do que pela interface gráfica.

O Unity CLI não e um substituto do editor. E uma ferramenta complementar que expõe as operações mais comuns de gerenciamento de projeto via linha de comando: criar projetos, instalar packages, rodar testes, fazer builds e executar scripts C# sem abrir o editor.

Para equipes de game development que querem automatizar pipelines de build ou integrar Unity em fluxos de CI/CD como GitHub Actions ou GitLab CI, o Unity CLI e uma adição muito bem-vinda. A ferramenta estava disponível de forma limitada por algum tempo, mas o blog oficial da Unity publicou recentemente um post apresentando a CLI de forma mais ampla para a comunidade.

Como o Unity CLI funciona por dentro

O Unity CLI e um wrapper em torno das funcionalidades headless que o Unity Editor já tinha ha anos. O editor sempre suportou modo batch (flag -batchmode), que permitia rodar scripts e builds sem interface gráfica, mas a experiência era trabalhosa: era necessário passar flags longas, saber quais métodos chamar via -executeMethod e lidar com saída de log pouco estruturada.

O CLI resolve esses problemas oferecendo uma interface moderna com subcomandos bem definidos, saída formatada e documentação clara. Por baixo, ainda usa o mecanismo de batch mode do editor, mas envolve tudo em uma experiência muito mais amigável.

A CLI e instalada separada do editor e pode gerenciar múltiplas versões do Unity instaladas na máquina, escolhendo automaticamente qual versão usar baseado no arquivo ProjectSettings/ProjectVersion.txt do projeto que você esta trabalhando.

💡
Dica

O Unity CLI detecta automaticamente a versão do Unity do projeto lendo o ProjectVersion.txt. Você não precisa especificar a versão manualmente na maioria dos comandos.

Principais comandos disponíveis

O Unity CLI cobre as operações mais comuns do dia a dia de um projeto Unity:

  • unity new: cria um novo projeto Unity em um diretório especificado, com template opcional (2D, 3D, URP, HDRP).
  • unity open: abre um projeto no Unity Editor a partir do terminal.
  • unity build: executa o build do projeto para uma plataforma alvo sem abrir o editor.
  • unity test: roda os testes do projeto (Unity Test Framework) no modo batch.
  • unity package: gerência packages do Unity Package Manager (instalar, remover, listar).
  • unity run: executa um método C# estático específico sem abrir o editor.

A lista de comandos ainda esta crescendo. A Unity tem planos de expandir a CLI com mais funcionalidades de gerenciamento de licenças, deploy e integração com Unity Services (Cloud Build, Analytics etc.).

⚠️
Atenção

O Unity CLI ainda esta em desenvolvimento ativo e alguns comandos podem mudar entre versões. Consulte sempre a documentação oficial antes de usar em pipelines de produção.

Como instalar o Unity CLI

A instalação do Unity CLI e separada do Unity Hub e do Editor. Siga os passos:

Passo 1 - Instale via npm (forma recomendada):

npm install -g @unity/unity-cli

Passo 2 - Verifique a instalação:

unity --version

Passo 3 - Faca login com sua conta Unity:

unity login

Passo 4 - Crie seu primeiro projeto pelo terminal:

unity new meu-jogo --template 2d
cd meu-jogo
unity open

Para usuários Linux e macOS, o processo e idêntico. No Windows, use o terminal com permissões de administrador se encontrar problemas de permissão durante a instalação do npm global.

Exemplo prático: build automatizado no GitHub Actions

O caso de uso mais poderoso do Unity CLI e em pipelines de CI/CD. Aqui esta um exemplo de workflow do GitHub Actions para fazer build automático de um projeto Unity para WebGL a cada push na branch main:

name: Unity Build
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Unity CLI
        run: npm install -g @unity/unity-cli
      
      - name: Unity Login
        run: unity login --token ${{ secrets.UNITY_TOKEN }}
      
      - name: Build WebGL
        run: unity build --platform webgl --output ./build/webgl
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: webgl-build
          path: ./build/webgl

Esse workflow elimina a necessidade de configurar o Unity Editor completo no runner de CI, reduzindo significativamente o tempo de setup do ambiente de build. O token de autenticação e armazenado como secret no repositório do GitHub.

🚀
Pro tip

Use a flag --log-file no comando de build para redirecionar os logs do Unity para um arquivo. Isso facilita muito o debug quando uma build falha no CI, pois você pode fazer upload do log como artifact junto com o build.

Comparação: Unity CLI vs alternativas anteriores

Antes do Unity CLI oficial, a comunidade usava soluções alternativas para automação de builds Unity. As principais eram:

game-ci/unity-actions (GitHub Actions): uma action da comunidade muito popular que configura o Unity em runners de CI usando Docker. Funciona bem mas exige um container completo do Unity, o que pode ser pesado em termos de storage e tempo de pull.

Scripts batch mode manuais: invocar o Unity diretamente com flags como -batchmode -executeMethod MyClass.MyMethod -quit. Funciona, mas e verboso, pouco documentado e a saída de erro e difícil de parsear.

Unity Build Automation (antigo Cloud Build): serviço pago da própria Unity que faz builds na nuvem. Muito mais simples de configurar, mas tem custo e menos controle sobre o ambiente.

O Unity CLI oficial se posiciona entre as alternativas manuais e o Cloud Build: mais simples que scripts batch, mais barato que o Cloud Build, e com melhor experiência de desenvolvedor que qualquer alternativa da comunidade.

Pontos positivos e limitações do Unity CLI

O que funciona muito bem: a instalação via npm e familiar para qualquer dev que já usou ferramentas JavaScript. A detecção automática de versão do Unity elimina um ponto de fricção clássico em projetos com múltiplos colaboradores usando versões diferentes.

Limitações reais: o CLI ainda não cobre toda a funcionalidade do modo batch. Algumas operações avançadas (como importação de assets customizados, configuração de iluminação baked ou processamento de asset bundles complexos) ainda exigem scripts C# invocados via unity run. A documentação ainda esta crescendo e alguns casos de borda não estão bem cobertos.

🔴
Cuidado

O Unity CLI ainda não suporta todas as versões do Unity. Verifique na documentação oficial se a versão do seu projeto e compatível antes de migrar seu pipeline de CI para o CLI.

Maturidade: sendo uma ferramenta relativamente nova, o Unity CLI pode ter bugs e mudanças de API entre versões. Para projetos em produção, avalie bem antes de depender do CLI em pipelines críticos sem ter um plano de fallback para o modo batch manual.

Casos de uso reais: quem se beneficia mais

O Unity CLI não e para todos os projetos Unity, mas e muito relevante para perfis específicos:

Estúdios indie com times pequenos: automatizar builds libera tempo do desenvolvedor para criar jogo de verdade. Um pipeline básico de CI que faz build automático a cada PR pode pegar bugs de compilação antes que cheguem na main branch.

Times com projetos multi-plataforma: fazer builds para PC, Mobile e WebGL manualmente e tedioso. O Unity CLI permite scriptar esses builds e rodar todos em paralelo no CI, reduzindo o tempo total de build da semana.

Devs que trabalham com Unity Services: a integração planejada do CLI com Unity Analytics, Multiplayer e outras ferramentas de backend pode simplificar muito o setup de projetos que usam o ecossistema completo da Unity.

Freelancers e professores: criar e configurar projetos Unity rapidamente via terminal e muito mais eficiente do que clicar pelo Unity Hub, especialmente quando você esta criando múltiplos projetos de exemplo ou projetos de aula.

Dicas e boas práticas com o Unity CLI

💡
Dica 1 - Versione o arquivo de configuração do CLI

Se o projeto tem configurações específicas de build, crie um arquivo unity-cli.json na raiz do repositório e versione junto com o código. Isso garante que todos no time usem as mesmas configurações de build sem precisar documentar flags manualmente.

💡
Dica 2 - Use unity test no pre-commit hook

Configure um pre-commit hook que rode unity test antes de cada commit. Isso garante que testes unitários passam antes do código entrar no repositório, sem precisar esperar o CI para descobrir regressões.

🚀
Pro tip - Combine com Docker para builds reproduzíveis

Para builds 100% reproduzíveis, combine o Unity CLI com um Dockerfile que define exatamente qual versão do Unity, das dependências e do sistema operacional usar. Isso elimina o problema de funcionar na minha máquina mas não no CI.

⚠️
Atenção - Licenças em ambientes headless

Rodar Unity em modo batch ou via CLI exige uma licença valida. Em servidores de CI, você precisa de uma licença do tipo Unity Build Server ou usar o mecanismo de ativação manual. Verifique os termos da sua licença antes de configurar o CLI em infraestrutura cloud.

Vale a pena adotar o Unity CLI agora?

Para projetos novos que precisam de automação de build: sim, vale experimentar já. O Unity CLI simplifica o setup inicial de pipelines de CI/CD e a experiência e bem melhor que o modo batch manual.

Para projetos existentes com pipelines de CI funcionando (via game-ci ou scripts próprios): avalie com calma. A migração tem custo e o CLI ainda não e 100% estável. A menos que você esteja tendo problemas específicos com a solução atual, pode esperar mais alguns meses até o CLI ganhar mais maturidade e cobertura de funcionalidades.

O mais importante: comece pequeno. Use o Unity CLI em um projeto de teste ou em um pipeline de dev antes de colocar em produção. Assim você aprende as peculariedades da ferramenta sem arriscar o pipeline crítico da equipe.