Você rodou o comando de instalação, deu certo, e aí o Grok Build não te deixou entrar. Esse é o tropeço mais comum no setup do Grok Build — e não é bug. O acesso ao beta tá amarrado a uma assinatura específica da xAI, não a ter uma API key ou uma conta no X. Antes de gastar tempo debugando seu shell, a primeira coisa a verificar é o acesso da conta. Esse guia cobre o caminho completo de instalação pra macOS, Linux, WSL e Windows, mais a parte de auth, TUI e setup headless que de fato te leva até uma sessão funcionando.
Baseado na documentação da xAI vigente em 26 de maio de 2026. O Grok Build tá em beta inicial — comandos de instalação, requisitos de acesso e funcionalidades mudam com frequência. Confirma com os docs oficiais da xAI antes de depender de qualquer passo específico.
O que você precisa antes de instalar o Grok Build
Acesso à conta e status do beta
O Grok Build tá em beta inicial. O acesso é limitado a tiers específicos de assinatura da xAI — no lançamento, o que saiu foi assinantes SuperGrok Heavy, e a cobertura do instalador Windows mencionou também SuperGrok e X Premium+. O ponto principal: o acesso ao beta tá amarrado à sua assinatura, não a uma API key xAI comum nem a uma conta básica do X.
É daí que vem o problema mais comum do tipo "instalei mas não consigo usar". A instalação dá certo independentemente da sua assinatura; o gate é no passo de autenticação. Confirma que sua conta tem uma assinatura elegível antes de instalar, e faz login no primeiro launch com essa conta. Confirma os requisitos atuais nos docs oficiais da xAI, já que os tiers de acesso ao beta podem mudar.
Suporte a macOS, Linux, WSL e Windows
Status de suporte em fins de maio de 2026 — precisa de leitura atenta porque mudou no meio do mês:
- macOS: suportado nativamente
- Linux: suportado nativamente
- Windows via WSL2: suportado — foi o caminho documentado pra devs Windows na maior parte do beta
- Windows PowerShell: a xAI lançou um instalador PowerShell em 25 de maio de 2026
A situação Windows tá genuinamente em transição. Na maior parte do beta, o caminho documentado pra Windows era WSL2 (com alguns comandos relatados como inconsistentes mesmo lá). O instalador PowerShell de 25 de maio adicionou um caminho mais direto pro Windows. Se você tá no Windows, as duas opções existem agora — mas, sendo uma adição recente ao beta, o caminho PowerShell pode ter arestas que os caminhos mais estabelecidos (macOS/Linux/WSL) não têm. Um build Win32 nativo totalmente maduro ainda foi descrito como roadmap, sem data confirmada.
"Grok Build app" é um nome meio enganoso que vale a pena esclarecer: o Grok Build é uma ferramenta de linha de comando (CLI) com uma interface de terminal interativa (TUI), não um app desktop GUI standalone. Você roda no terminal, não a partir de uma pasta de aplicativos.
Instalando o Grok Build pelo CLI
Caminho de instalação no macOS, Linux e WSL
A instalação é um comando único:
curl -fsSL https://x.ai/cli/install.sh | bashIsso baixa e roda o script de instalação. No WSL2, roda dentro do seu ambiente WSL Linux (não no CMD ou PowerShell do Windows) — WSL2 é um ambiente Linux, então o caminho de instalação Linux se aplica.
Depois de instalar, verifica:
grok --versionSe o grok não for encontrado, a localização da instalação não tá no seu PATH. Vê a seção de troubleshooting abaixo.
Caminho de instalação no Windows PowerShell
Desde 25 de maio de 2026, usuários Windows têm um instalador PowerShell nativo:
irm https://x.ai/cli/install.ps1 | iexIsso baixa e roda o script de instalação PowerShell. Roda numa sessão PowerShell (não no CMD). Como essa é uma adição recente ao beta, confirma o comando atual nos docs oficiais — comandos de instalador no início costumam mudar nas primeiras semanas após o lançamento.
Pra devs Windows que já estavam usando o caminho WSL2, não tem urgência em migrar pro PowerShell — o caminho WSL2 continua funcional. O instalador PowerShell é mais relevante pra quem prefere não usar WSL.
Primeiro launch e autenticação no navegador
No primeiro launch, o Grok Build abre uma janela do navegador pra autenticação OAuth (conforme os docs de getting-started):
cd your-project
grokEntra com a conta que tem sua assinatura xAI elegível. Esse é o passo onde o acesso ao beta é aplicado — se sua conta não tem uma assinatura elegível, a autenticação não vai liberar o acesso, mesmo com instalação bem-sucedida. O fluxo OAuth via navegador é o padrão pra uso em workstation; pra ambientes headless, vê o caminho de API key abaixo.
Começando sua primeira sessão no Grok Build
Rode o Grok Build dentro de um repo
O Grok Build opera no repositório do seu diretório atual. Entra no seu projeto antes de fazer o launch:
cd ~/projects/my-app
grokUma boa primeira ação é confirmar que o agente pegou o contexto do seu repo. Roda o comando inspect pra ver o que o Grok detectou:
grok inspectIsso mostra fontes de config, instruções, skills, plugins, hooks e MCP servers que o Grok carregou pro diretório atual. É o jeito mais rápido de confirmar que seu AGENTS.md e quaisquer MCP servers foram de fato carregados antes de confiar no agente pra uma mudança real.
Use a TUI pra codar de forma interativa
O modo interativo padrão é uma TUI (terminal UI) — uma sessão estruturada de ida-e-volta no seu terminal. Você digita um objetivo de alto nível e o Grok Build responde com um plano e ações propostas.
O Plan Mode é a feature que a xAI mais destaca no Grok Build. Em vez de um plano linear em texto, ele gera um grafo de subtarefas com estado por nó exibido na TUI, e pode ativar subagentes em paralelo em branches independentes. Você descreve um objetivo ("adiciona rate limiting no middleware do Express com Redis"), o Grok monta um plano estruturado com arquivos a tocar e comandos a rodar, e você aprova antes de executar.
Trocar de modelo dentro da TUI: /model <name>.
Testa o modo headless pra scripts e automação
Pra uso não-interativo — pipelines de CI, cron jobs, scripts — o Grok Build suporta modo headless via flag -p:
grok -p "add integration tests for the auth module"O modo headless roda o agente sem a TUI interativa, adequado pra pipelines automatizados. O Grok Build também suporta o ACP (Agent Client Protocol) pra integrações de automação mais profundas. Em ambientes headless, você vai usar autenticação por API key em vez do OAuth via navegador (próxima seção).
Configurando o Grok Build pro fluxo de desenvolvimento
Autenticação por API key em ambientes sem navegador
O login via navegador funciona numa workstation, mas quebra num servidor headless, num CI runner ou num container remoto sem navegador. Pra esses ambientes, define uma variável de ambiente com uma API key xAI:
export GROK_CODE_XAI_API_KEY="xai-..."Cria a key em console.x.ai (API Keys → Create API Key). Injeta a partir de um cofre de segredos no CI; nunca faz commit dela no seu repositório. Com a variável de ambiente setada, o Grok Build autentica sem abrir navegador, viabilizando uso headless e automatizado.
Modelos customizados e descoberta de config
O Grok Build roda no grok-build-0.1 por padrão — um modelo focado em código, com janela de contexto de 256K tokens, aceitando entrada de texto e imagem (model reference). (Obs.: cobertura da semana de lançamento citando grok-code-fast-1, agora deprecated, ou uma "janela de contexto de 2M" tá desatualizada — confirma o modelo atual em docs.x.ai.)
O Grok Build suporta flexibilidade de modelo, incluindo roteamento via OpenRouter pra usar Claude, GPT ou LLMs locais pelo mesmo CLI. Configura o modelo no modo headless via flags ou na TUI via /model <name>. Roda grok inspect pra confirmar quais fontes de config e settings de modelo foram descobertos pro diretório atual.
AGENTS.md, skills, hooks e MCP servers
O Grok Build descobre e carrega automaticamente a configuração padrão de agente:
- AGENTS.md e CLAUDE.md: o Grok Build reconhece os dois. Se você tá migrando do Claude Code, seu CLAUDE.md funciona sem alterações.
- Skills: o Grok reconhece o formato de skills da Anthropic. Copia a pasta de skills pro diretório do projeto ou pro
~/.grok/skills/e o CLI carrega automaticamente. - MCP servers: MCP servers já configurados são pegos automaticamente.
- Hooks e plugins: descobertos e carregados a partir de localizações padrão.
Essa compatibilidade zero-migração com o formato de config do Claude Code é uma decisão de design deliberada — reduz o custo de troca pra devs vindos do Claude Code. Roda grok inspect depois de configurar pra confirmar que tudo foi carregado.
Problemas comuns no setup
Problemas de shell e PATH
grok: command not found depois de instalar: a localização da instalação não tá no seu PATH. O script de instalação informa onde colocou o binário — adiciona esse diretório no seu PATH dentro do seu shell profile (.bashrc, .zshrc ou equivalente), depois reinicia o shell ou faz source do profile. Confirma com which grok (macOS/Linux/WSL).
Script de instalação falha no meio: confirma que o curl tá instalado e que você tem acesso de rede pro x.ai. Em redes restritas, o passo de download do script pode tá bloqueado.
Confusão entre Windows e WSL
Rodar o comando de instalação Linux no PowerShell: o curl ... | bash é pra macOS/Linux/WSL. No PowerShell, usa o instalador PowerShell (irm ``https://x.ai/cli/install.ps1`` | iex) no lugar. Misturar os dois é um erro comum no Windows.
Confusão entre WSL e Windows nativo: se você instalou via WSL2, roda o grok dentro da sessão WSL Linux, não no CMD/PowerShell do Windows. A instalação WSL e a instalação PowerShell são separadas — um binário instalado no WSL não fica disponível no PowerShell nativo do Windows e vice-versa. Escolhe um caminho e mantém ele consistente.
Comandos com comportamento inconsistente no WSL: alguns comandos foram relatados com comportamento inconsistente sob WSL durante o beta. Se você bater em comportamento inesperado no WSL e tá no Windows, o instalador PowerShell agora é uma alternativa pra testar.
Problemas de auth ou acesso à conta
"Instalei mas não consigo acessar": é quase sempre o gate de assinatura. A instalação dá certo pra qualquer um; o acesso exige uma assinatura xAI elegível, amarrada à conta com que você se autentica. Confirma que sua conta tem um tier elegível e que você tá entrando com exatamente essa conta no fluxo OAuth.
Navegador não abre / ambiente headless: usa o caminho da variável GROK_CODE_XAI_API_KEY em vez do OAuth via navegador. O fluxo via navegador só funciona onde tem navegador disponível.
Limites do beta e verificações de segurança
Trate o comportamento de beta inicial como instável
O Grok Build tá em beta inicial. Comandos de instalação, nomes de modelo, requisitos de acesso e funcionalidades já mudaram dentro do período de beta e provavelmente vão mudar de novo. Não monta um fluxo crítico de produção em cima de comportamento beta que pode mudar. Pra experimentação e avaliação, beleza; pra qualquer coisa de que você depende, espera mais estabilidade ou mantém uma ferramenta mais estabelecida (Claude Code, Codex CLI) como caminho de produção.
Revise os diffs antes de aceitar mudanças
Isso vale pra qualquer agente de código, e em dobro pra um em beta: revisa todo diff antes de aceitar. O fluxo de aprovar-antes-de-executar do Plan Mode ajuda — você vê o plano antes do agente agir — mas aprovar o plano não substitui revisar as mudanças reais do código. Lê o diff, confirma que ele faz o que você queria, e não aceita mudanças que você não revisou.
Evite rodar comandos pouco claros sem aprovação
O Grok Build pode rodar comandos no terminal como parte do agent loop. Numa ferramenta em beta, sê conservador com o que você deixa rodar sem supervisão. Usa os gates de aprovação, não roda em modos auto-aprovados estilo --yolo num repositório ou sistema que você se importa, e tem cautela redobrada com comandos que mexem em estado fora do repo (instalação de pacotes, mudanças no sistema, qualquer coisa tocando em credenciais ou deploy). O fluxo plan-and-approve existe exatamente pra isso — usa.
FAQ
O que é o Grok Build CLI?
O Grok Build é o agente de código terminal-native da xAI — uma ferramenta de linha de comando (CLI) com uma TUI (interface de terminal interativa), lançada em beta em maio de 2026. Ele embute os modelos Grok da xAI (padrão: grok-build-0.1) diretamente no seu terminal, com Plan Mode (planejamento de tarefas em grafo com gates de aprovação), subagentes em paralelo, modo headless pra automação e compatibilidade com AGENTS.md, CLAUDE.md, skills no formato Anthropic e MCP servers. Compete com Claude Code e Codex CLI na categoria de agentes de código no terminal. É uma ferramenta CLI/TUI, não um app GUI standalone.
Como instalo o Grok Build no Windows?
Duas opções em fins de maio de 2026. O instalador PowerShell (lançado em 25 de maio de 2026): roda irm https://x.ai/cli/install.ps1 | iex numa sessão PowerShell. Ou via WSL2: instala o Windows Subsystem for Linux 2 e roda o comando de instalação Linux (curl -fsSL https://x.ai/cli/install.sh | bash) dentro do seu ambiente WSL. O caminho PowerShell é mais novo e pode ter arestas de beta; o caminho WSL2 foi o padrão documentado na maior parte do beta. Confirma as instruções atuais de instalação Windows nos docs oficiais da xAI, já que a história Windows tá evoluindo ativamente.
O Grok Build funciona no WSL?
Funciona. WSL2 (Windows Subsystem for Linux 2) foi o caminho Windows documentado na maior parte do beta — instala dentro do seu ambiente WSL Linux usando o comando de instalação Linux e roda o grok dentro da sessão WSL. Alguns comandos foram relatados com comportamento inconsistente sob WSL durante o beta. Se bater em problemas, o instalador PowerShell nativo (lançado em 25 de maio de 2026) é uma alternativa pra testar. Confirma o status atual de suporte ao WSL nos docs oficiais.
Por que não consigo acessar o Grok Build depois de instalar?
Quase sempre é o gate de assinatura. A instalação dá certo pra qualquer um, mas o acesso exige uma assinatura xAI elegível (no lançamento citaram SuperGrok Heavy; a cobertura Windows citou SuperGrok e X Premium+). O acesso ao beta tá amarrado à assinatura na conta com que você autentica no fluxo OAuth do navegador — não a ter uma API key ou uma conta básica do X. Confirma que sua conta tem uma assinatura elegível e que você tá entrando com exatamente essa conta. Confirma os requisitos atuais de acesso na documentação oficial da xAI, já que a elegibilidade do beta pode mudar.
Quando devs deveriam usar o Grok Build em vez de outro agente de código?
Considera o Grok Build se você quer avaliar os modelos Grok da xAI num fluxo de terminal, se valoriza o planejamento em grafo do Plan Mode com subagentes em paralelo, ou se você já tá no ecossistema xAI/SuperGrok. A compatibilidade zero-migração com o formato de config do Claude Code (CLAUDE.md, skills, MCP) deixa baixo o atrito pra testar lado a lado com o Claude Code. Mantém uma ferramenta mais estabelecida (Claude Code, Codex CLI) pra trabalho crítico de produção até o Grok Build chegar em GA — tá em beta inicial. Vale notar que o Grok Build, assim como Claude Code e Codex CLI, é um agente de código no terminal; ferramentas como o Verdent operam numa camada diferente, focada em fluxos multi-agente Plan-First com isolamento seguro com Git Worktree e diffs revisáveis em tarefas paralelas. O agente de terminal e a plataforma de fluxo endereçam partes diferentes da stack.
