# CLI da W8 Hub

> Instale o CLI w8 no Linux, macOS ou Windows, entre com o login pelo navegador ou use um token pessoal em scripts.

_Fonte: https://w8hub.com.br/docs/cli_

O CLI `w8` faz login na W8 Hub e lista recursos pelo terminal. Esta página mostra como instalar, entrar 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 <id da organização>` é 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 do CLI: ler seus dados, listar projetos e recursos, e iniciar, parar e 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 <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.

## Comandos

| Comando | Para que serve |
|---|---|
| `w8 login` | Entra. |
| `w8 whoami [--org <slug>] [--json]` | Mostra a sessão. |
| `w8 resources list [--org <slug ou id>] [--json]` | Lista os recursos. |
| `w8 logout [--org <slug>]` | Sai. |
| `w8 version` | Mostra a versão. |

## 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 <arquivo>`:

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

Ou, com arquivo:

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

Com token pessoal, `--org <id da organização>` é obrigatório em cada comando. `w8 whoami` não se aplica a token pessoal. A própria mensagem do CLI diz isso.

Se a organização estiver fora do alcance do token, o CLI responde que o token pessoal não alcança a organização e sai com código 1.

## 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 |

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