CLI da W8 Hub

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.

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).

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:

w8 version

Instalar no Windows

Sistema: Windows (amd64). Rode no PowerShell, sem precisar de administrador:

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:

w8 version

Entrar com w8 login

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 <e-mail> na organização <nome> (<slug>).

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

w8 link [--org <slug>] [--project <slug>] [--resource <slug>] [--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

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.

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

Antes ou depois do comando, o CLI aceita --debug, --org <slug ou id> e --token-file <arquivo>. 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:

w8 <comando> [valores...] [--org <slug ou id>] [--json] [--<filtro> <valor>] [--data <json>|--data-file <arquivo>|--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:

w8 deploy <id> --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

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 <arquivo> 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 <nome> escolhe esse nome, --force regrava um bloco que já existe e --dry-run mostra o que seria gravado.

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

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.

Usar com token pessoal

Em script, use o token pessoal. Para criar o token, veja Conectar o MCP. Passe o token pela variável W8_TOKEN ou pela opção --token-file <arquivo>:

export W8_TOKEN="w8_..."
w8 resources list --org <id da organização>

Ou, com arquivo:

w8 resources list --org <id da organização> --token-file <arquivo>

Com token pessoal, --org <id da organização> é 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

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.