# CLI da W8 Hub > Instale e entre no CLI w8, vincule o repositório a uma instalação, configure o MCP, rode comandos com as variáveis de ambiente e entenda quem pode ler o valor cru. _Fonte: https://w8hub.com.br/docs/cli_ O CLI `w8` faz login na W8 Hub, vincula o repositório a uma instalação e chama a API pelo terminal. Esta página mostra como instalar, entrar, vincular e usar, por organização. ## Duas formas de autenticar O CLI aceita dois métodos. Os dois funcionam em Linux, macOS e Windows. | | Login pelo navegador (`w8 login`) | Token pessoal | |---|---|---| | Como entra | `w8 login` abre o navegador, você escolhe a organização lá e digita no terminal o código que aparece | Você cria o token na sua conta e passa em `W8_TOKEN` ou `--token-file` | | Sessão | Uma por organização, guardada no cofre do sistema | Nenhuma sessão: o token vale por comando | | Organização | A da sessão. `--org` escolhe entre as suas sessões | `--org ` é obrigatório em cada comando | | `w8 whoami` | Funciona | Não se aplica | | Terminal | Precisa de terminal interativo | Funciona em script e em máquina sem terminal | | Indicado para | Uso diário no seu computador | Scripts, automação e várias organizações com a mesma credencial | No login pelo navegador, o servidor só aceita uma lista fechada de operações: ler seus dados e o nome da organização, listar as organizações e os projetos, listar os recursos, ler as variáveis de ambiente de uma instalação, e iniciar, parar ou reiniciar um recurso. Qualquer outra operação é recusada. ## Instalar no Linux e no macOS A versão atual é a 1.235.1. Sistemas: Linux (amd64 e arm64) e macOS (amd64 e arm64). ```bash curl -fsSL https://bucket-cli.w8hub.s3.w8hub.com.br/v1.235.1/install.sh | sh ``` O instalador baixa uma versão fixa, confere o sha256 contra o `checksums.txt` da mesma origem antes de instalar e não pede token do GitHub. O binário vai para `~/.local/bin` e o PATH entra pelo `~/.profile`. Abra um shell novo e confira: ```bash w8 version ``` ## Instalar no Windows Sistema: Windows (amd64). Rode no PowerShell, sem precisar de administrador: ```powershell irm https://bucket-cli.w8hub.s3.w8hub.com.br/v1.235.1/install.ps1 | iex ``` O instalador baixa uma versão fixa, confere o sha256 contra o `checksums.txt` da mesma origem e não pede token do GitHub. Ele instala `w8.exe` em `%LOCALAPPDATA%\w8\bin` e põe essa pasta no PATH do usuário. Abra um terminal novo e confira: ```powershell w8 version ``` > [!TIP] > O binário não é assinado. Se você baixar o arquivo pelo navegador, o Windows pode mostrar o aviso do SmartScreen. Rodando o instalador pelo terminal, o aviso não apareceu. ## Entrar com w8 login ```bash w8 login ``` O `w8 login` abre o navegador na tela de autorização da W8 Hub. Escolha a organização lá, aprove, e digite no terminal o código que aparece no navegador. No fim, o CLI confirma: `Logado como na organização ().` O login só funciona em terminal interativo. Sem terminal, ele cancela e não grava nada. A sessão é por organização: uma sessão para cada uma. Use `--org` para dizer qual organização o comando usa. Onde a credencial fica: - macOS: Keychain. - Windows: Gerenciador de Credenciais. - Linux: o cofre do sistema (`secret-tool`). Se não houver, um arquivo com permissão restrita. Nesse caso o login avisa no final. ## Vincular o repositório com w8 link ```bash w8 link [--org ] [--project ] [--resource ] [--share] ``` O `w8 link` grava um arquivo `.w8.json` na raiz do repositório com a organização, o projeto e a instalação escolhidos, e acrescenta esse arquivo ao `.gitignore`. Com `--share`, ele grava o arquivo sem mexer no `.gitignore`, para o vínculo ser compartilhado com o time. Os comandos que precisam do vínculo procuram o `.w8.json` na pasta atual e nas pastas acima, então você pode rodar de dentro de um subdiretório do repositório. ## Conferir o vínculo com w8 status e w8 open ```bash w8 status ``` O `w8 status` mostra o vínculo, a origem do vínculo, o host da API e a validade da credencial. Ele **não chama a API**: é o comando para descobrir o que está configurado quando algo falha. ```bash w8 open [--print] ``` O `w8 open` abre a instalação vinculada no painel da W8 Hub. Com `--print`, ele só imprime a URL, sem abrir o navegador. ## Comandos | Comando | Para que serve | |---|---| | `w8 login` | Entra. | | `w8 whoami [--org ] [--json]` | Mostra a sessão. | | `w8 resources list [--org ] [--json]` | Lista os recursos. | | `w8 link [--org] [--project] [--resource] [--share]` | Grava o `.w8.json` do repositório. | | `w8 status` | Mostra o vínculo, a origem, o host da API e a validade da credencial, sem chamar a API. | | `w8 open [--print]` | Abre a instalação no painel; `--print` só imprime a URL. | | `w8 mcp install [--client ] [--scope user\|project]` | Grava o bloco MCP do w8 no cliente escolhido. | | `w8 mcp status` | Faz `initialize` e `tools/list` de verdade e diz o protocolo, as ferramentas e a organização. | | `w8 env run [--org ] -- ` | Roda um comando com as variáveis da instalação vinculada. | | `w8 logout [--org ]` | Sai. | | `w8 version` | Mostra a versão. | Antes ou depois do comando, o CLI aceita `--debug`, `--org ` e `--token-file `. O `--debug` mostra o que o CLI fez sem nunca registrar a credencial. ## Comandos gerados da API Além dos comandos fixos, o CLI gera um comando para cada operação do spec público da W8 Hub: ```bash w8 [valores...] [--org ] [--json] [-- ] [--data |--data-file |--data-stdin] ``` Os filtros de consulta viram opções com o nome do campo. O corpo do pedido vai em `--data`, `--data-file` ou `--data-stdin`. O `--refresh` baixa o catálogo de comandos de novo, para quando a API ganha uma operação. Há atalhos para as operações do dia a dia: `restart`, `logs`, `deploy`, `stop`, `start`, `db`, `storage` e `domain`. O `deploy` tem acompanhamento: ```bash w8 deploy --follow [--timeout 30m] ``` O `--follow` acompanha o deploy até o fim, com teto de 30 minutos ou 600 consultas a cada 3 segundos. `Ctrl-C` sai do acompanhamento **sem cancelar o deploy**. ## Instalar o MCP com o CLI ```bash w8 mcp install --client claude-code ``` O `w8 mcp install` grava o bloco MCP do w8 no arquivo do cliente escolhido. Clientes: `claude-code`, `cursor`, `vscode` ou `all`. O escopo é `user` ou `project` (`--user` e `--project` são os atalhos). O `--path ` grava em um arquivo específico, mas só vale com `--client vscode` (ou `all`) no escopo `user`. Nos outros clientes e no escopo `project`, o arquivo é o do próprio cliente. O token fica no arquivo só como `${NOME}`, nunca como texto: você preenche a variável no seu ambiente. `--token-env ` escolhe esse nome, `--force` regrava um bloco que já existe e `--dry-run` mostra o que seria gravado. ```bash w8 mcp status ``` O `w8 mcp status` faz `initialize` e `tools/list` de verdade contra o servidor e mostra o protocolo, as ferramentas e a organização. ## Rodar um comando com as variáveis da instalação ```bash w8 env run -- npm start ``` O `w8 env run` injeta as variáveis da instalação vinculada no processo filho. Ele não escreve arquivo, o código de saída é o do filho e `Ctrl-C` vai para o filho. Precisa de `.w8.json` na pasta atual ou acima. > [!WARNING] > O processo filho lê os valores do próprio ambiente. Qualquer pessoa ou processo com controle da máquina consegue lê-los enquanto o comando roda. É o mesmo limite de exportar a variável no shell. ## Usar com token pessoal Em script, use o token pessoal. Para criar o token, veja [Conectar o MCP](https://w8hub.com.br/docs/conectar-mcp). Passe o token pela variável `W8_TOKEN` ou pela opção `--token-file `: ```bash export W8_TOKEN="w8_..." w8 resources list --org ``` Ou, com arquivo: ```bash w8 resources list --org --token-file ``` Com token pessoal, `--org ` é obrigatório em cada comando. A exceção é o `organization-list`, que dispensa o `--org` e lista as organizações que o token alcança. `w8 whoami` não se aplica a token pessoal. Se a organização estiver fora do alcance do token, o CLI responde que o token pessoal não alcança a organização. ## Valor cru das variáveis A leitura do valor cru de uma variável tem regras próprias: - Só para quem é Proprietário ou Administrador na organização. - O projeto não pode estar arquivado. - A instalação precisa estar no ar e a cobrança ativa. - Instalação parada recusa o valor cru, com o código 20 e a mensagem para iniciar a instalação. A lista mascarada continua livre para qualquer membro. Exportar (baixar) as variáveis segue permitido numa instalação parada, mesmo com a cobrança ativa: a janela de 30 dias só começa depois de desativar a cobrança. Um pedido feito na organização A para um alvo da organização B responde 404. ## Códigos de saída | Código | Significado | |---|---| | 0 | ok | | 1 | erro | | 10 | credencial recusada ou sem sessão | | 11 | falha ao guardar ou ler a credencial | | 12 | logout só local: a sessão foi apagada deste computador, mas a revogação no servidor não foi confirmada. Revogue em Sessões, no painel da W8 Hub | | 13 | código expirado, recusado ou login cancelado | | 14 | sem vínculo: falta o `.w8.json`. Rode `w8 link` | | 20 | `w8 env run` falhou antes de o filho rodar: vínculo, recurso, licença ou rede | ## Limites conhecidos - `w8 login` só funciona em terminal interativo. - O CLI guarda uma sessão por organização. - Com token pessoal, `--org` é obrigatório em cada comando e `w8 whoami` não se aplica. - O binário do CLI não é assinado. No Windows, o SmartScreen pode avisar se o arquivo for baixado pelo navegador. - No Windows, o CLI existe só para amd64. - No Linux sem `secret-tool`, a credencial vai para um arquivo com permissão restrita. - O instalador baixa uma versão fixa. A URL leva o número da versão. - O `w8 deploy --follow` para no teto de 30 minutos ou de 600 consultas, mesmo que o deploy continue. - O `w8 env run` não esconde as variáveis do processo filho nem de quem controla a máquina.