> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyzecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Opere a Hyze Cloud pelo terminal. Faça deploy, acompanhe a build, leia os logs e configure o acesso.

A CLI oficial da Hyze Cloud se chama `hyze`. Ela cobre o ciclo de deploy de ponta a ponta: entrar na conta, listar apps, fazer deploy, acompanhar a build, ler os logs e conferir o que está no ar, sem sair do terminal.

<CardGroup cols={2}>
  <Card title="Instalação" icon="download" href="#instalação">
    Node 18+ ou Bun, um comando.
  </Card>

  <Card title="Primeiros passos" icon="rocket" href="#primeiros-passos">
    Do login ao app no ar.
  </Card>
</CardGroup>

## Instalação

```bash theme={"system"}
npm install -g @hyze-cloud/cli
# ou
bun add -g @hyze-cloud/cli

hyze --version
```

Roda em **Node 18+** e **Bun**.

## Primeiros passos

<Steps>
  <Step title="Guarde sua API key">
    Crie uma chave no [dashboard](http://hyzecloud.com/dashboard) em **Settings → Developer** e guarde com `hyze login`. A CLI confere a chave contra a API antes de salvar.

    ```bash theme={"system"}
    hyze login
    ```
  </Step>

  <Step title="Veja o que existe no workspace">
    ```bash theme={"system"}
    hyze projects
    ```
  </Step>

  <Step title="Faça deploy">
    ```bash theme={"system"}
    hyze deploy . --name my-api --runtime bun --port 3000 --subdomain my-api.hyzecloud.app
    ```

    Dentro de uma pasta de app, `hyze deploy .` usa o projeto já ligado à pasta (veja [`.hyzerc.json`](#arquivos-de-configuração)).
  </Step>

  <Step title="Confira o que está no ar">
    ```bash theme={"system"}
    hyze status my-api
    hyze logs my-api --follow
    ```
  </Step>
</Steps>

## Comandos

| Comando                                   | O que faz                                                   |
| ----------------------------------------- | ----------------------------------------------------------- |
| `hyze login`                              | guarda uma API key, depois de conferir contra a API         |
| `hyze logout`                             | remove a chave guardada do perfil ativo                     |
| `hyze projects`                           | lista os apps do workspace                                  |
| `hyze deploy [caminho]`                   | empacota, envia e acompanha a build                         |
| `hyze deployments [appId] [deploymentId]` | histórico de builds, ou uma build com o tempo de cada etapa |
| `hyze logs [appId] [deploymentId]`        | saída do app, ou o log da build daquela tentativa           |
| `hyze status [appId]`                     | o estado atual do app                                       |

`appId` é opcional onde o app é o assunto: o [`.hyzerc.json`](#arquivos-de-configuração) liga um app à pasta, então dentro do projeto `hyze status`, `hyze logs` e `hyze deploy .` funcionam sem argumento.

## Tela interativa

Rodar `hyze` sem argumento abre uma tela no terminal, em vez de imprimir a ajuda (`hyze --help` continua imprimindo a ajuda). Ela lê a mesma API, pelos mesmos comandos:

```
Projects                                                       4 projects

> ● Running    shop-api                shop-api.hyzecloud.app
  ○ Stopped    docs                    docs.hyzecloud.app
  ◐ Deploying  worker                  worker.hyzecloud.app
  ✕ Error      billing                 billing.hyzecloud.app

↑↓ Navigate · Enter Open · / Search · ? Help · q Quit
```

`Enter` abre o app em destaque, com o estado, a URL, os domínios que ele atende e as variáveis com que roda:

```
Projects › shop-api

● Running

URL           https://shop-api.hyzecloud.app
Last deploy   Success · 3h ago

Domains
  shop.example.com  Active · certificate active
CNAME         apps.hyzecloud.app

Environment
  API_KEY       hyze_abcd…wxyz
  DATABASE_URL  postgre…hop

d Deploy · r Restart · s Stop · b Builds · o Open in the browser · l Logs
e Set a variable · a Add a domain · v Show the values · Esc Back · ? Help · q Quit
```

As variáveis aparecem mascaradas, reconhecíveis mas não usáveis. `v` mostra os valores em texto e esconde de novo. `e` define uma variável no formato `KEY=value`, o mesmo de `-e`, e pergunta antes de gravar, porque o app reinicia para aplicar.

`s` é o verbo que muda algo: `Stop` com o app no ar, `Start` quando não está. Parar tira o app do ar, então também pergunta antes, e nada sai até você responder. `r` reinicia, `o` abre no navegador, `l` mostra os logs e `a` adiciona um domínio, dizendo onde apontar o DNS.

## Autenticação e configuração

O `hyze login` valida a chave antes de guardar. No terminal, o que você cola aparece como `*` a cada caractere, então um paste é visível sem expor o segredo. Em pipe ou com `--key <hyze_...>` a pergunta é pulada, que é como o CI alimenta a CLI:

```bash theme={"system"}
printf '%s' "$HYZE_API_KEY" | hyze login --no-verify
```

### Arquivos de configuração

| Local                                   | Para que serve                                               |
| --------------------------------------- | ------------------------------------------------------------ |
| `~/.config/hyze/config.json`            | perfis, perfil ativo e saída padrão (modo `0600`)            |
| `.hyzerc.json` (ancestral mais próximo) | padrões por app: `appId`, `apiUrl`, `workspaceId`, `profile` |

```json theme={"system"}
// .hyzerc.json
{ "appId": "app_abc123", "workspaceId": "org_abc", "apiUrl": "https://api.hyzecloud.com/api" }
```

A precedência, do mais forte para o mais fraco, é **flag → variável de ambiente → `.hyzerc.json` → perfil ativo → padrão**. Uma variável vazia conta como ausente, então `HYZE_API_KEY=""` não sobrescreve o perfil.

### Variáveis de ambiente

| Variável                              | Efeito                                         |
| ------------------------------------- | ---------------------------------------------- |
| `HYZE_API_KEY`                        | API key                                        |
| `HYZE_API_URL` ou `HYZE_API_BASE_URL` | base da API. Um host sem caminho recebe `/api` |
| `HYZE_WORKSPACE_ID`                   | workspace para escopo das requisições          |
| `HYZE_PROFILE`                        | nome do perfil                                 |
| `HYZE_OUTPUT`                         | `table`, `json`, `ndjson` ou `text`            |
| `HYZE_CONFIG` ou `HYZE_CONFIG_DIR`    | arquivo ou diretório de configuração           |
| `NO_COLOR`                            | desliga as cores                               |

## Opções globais

```
--profile <name>      perfil de configuração
--api-key <key>       API key (sobrepõe ambiente e perfil)
--api-url <url>       base da API
--workspace <id>      workspace para escopo das requisições
--config <path>       caminho do arquivo de configuração
--timeout <seconds>   timeout por requisição (padrão 60)
-o, --output <format> table | json | ndjson | text
--json                atalho para -o json (a resposta da API, intacta)
--no-color            desliga as cores
-q, --quiet           silencia a saída informativa
--verbose             registra cada requisição HTTP e mais detalhe
```

## Usar em scripts

`table` é o padrão quando a saída é um terminal, e `json` quando não é. Ou seja, encanar a saída sempre entrega JSON, sem você pedir.

<Callout>
  O resultado vai para **stdout**; progresso e mensagens vão para **stderr**. Por isso `hyze deployments app_1 --json | jq '.deployments[0].status'` é seguro.
</Callout>

O `--json` entrega a resposta da API sem reformatar, então não existe um "formato da CLI" para acompanhar:

| Comando                    | O que sai                                                                 |
| -------------------------- | ------------------------------------------------------------------------- |
| `projects`                 | `{ success, apps, meta }`                                                 |
| `deployments <appId>`      | `{ success, deployments, currentDeploymentId, activeDeploymentId, meta }` |
| `deployments <appId> <id>` | `{ success, deployment, timeline }`                                       |
| `logs <appId>`             | `{ success, logs }`                                                       |
| `deploy`                   | a build concluída. Com `--no-wait`, a resposta do envio                   |
| `status <appId>`           | o estado que a CLI resolveu, sempre no mesmo formato                      |

`status` é o único comando que resolve em vez de repassar. A API nem sempre consegue ver o app, e um `stopped` inventado seria lido como "o app está fora do ar".

## Deploy

As flags que você mais usa: `--name`, `--app <appId>` para refazer o deploy, `--runtime node|bun|python`, `--memory <mb>`, `--port` e `--subdomain` (juntos), `--env KEY=VALUE` (repetível), `--env-file`, `--start-command`, `--install-command`, `--build-command`, `--machine`, `--exclude` e `--include`, `--no-wait`, e `--repo <owner/name> [--branch] [--auto-deploy]` para GitHub.

Sem `--runtime`, a CLI pede para a API inspecionar o que foi enviado e usa o runtime detectado.

Durante a espera a CLI desenha o andamento no terminal, a partir do que a API mandou: o relógio da própria build, cada etapa com a duração que a plataforma carimbou e a fase que o worker escreveu para aquela build. Um fato que a API não mandou é uma linha que não aparece. **Não existe porcentagem**, porque o contrato não tem uma.

```
shop-api · building · 14s
  ✔ queue    4s
  ✔ install  5s
  ● build    4s
  worker · building · updated 2s ago
```

<Callout>
  A espera pertence ao terminal: em pipe ela não escreve nada, sem `\r`, sem ANSI, sem spinner. `--json` e `-o json` mantêm o payload exato.
</Callout>

### O que sobe no ZIP

Nesta ordem: os padrões de `--include` e `--exclude`, depois o `.hyzeignore` (estilo gitignore: `*`, `**`, `dir/`, `!keep`), depois `git ls-files --cached --others --exclude-standard` dentro de um repositório e, fora dele, uma varredura com ignores embutidos. `.git` e `node_modules` nunca sobem.

<Tip>
  O limite de upload não é um número fixo da CLI: antes de empacotar, ela lê o limite da plataforma e recusa um arquivo grande demais citando o número da própria plataforma.
</Tip>

## Logs

`hyze logs <appId>` imprime a saída do app (`--tail 1-1000`, `--timestamps`). `hyze logs <appId> <deploymentId>` imprime o log de instalação e build que a API guardou para aquela tentativa.

Com `--follow`, a CLI imprime só o que é novo. Para uma build, ela para quando a build termina; para o app, roda até você interromper.

```bash theme={"system"}
hyze logs my-api --follow -o text
```

## Erros e códigos de saída

Toda falha é uma linha mais o conserto, em stderr, sem stack trace. Use `--verbose` quando quiser o stack trace.

```
$ hyze projects
✖ UNAUTHORIZED · Unauthorized
  The key is missing, expired or revoked. Run `hyze login` to store a new one (Settings → Developer).
```

| Código | Significado                                                    |
| ------ | -------------------------------------------------------------- |
| 0      | sucesso                                                        |
| 1      | operação falhou, incluindo uma build que falhou                |
| 2      | erro de uso: flag inválida, chave ausente, app não selecionado |
| 3      | não autenticado ou sem permissão, incluindo limite de plano    |
| 4      | não encontrado                                                 |
| 5      | rate limit, incluindo o limite de builds do workspace          |
| 6      | erro de validação                                              |
| 7      | erro no servidor                                               |
| 8      | erro de rede ou timeout                                        |
| 130    | interrompido com Ctrl-C                                        |

### O estado `unknown`

`hyze status` imprime o que a plataforma reporta: `running`, `stopped`, `paused`, `restarting`, `deploying`, `error`, `exited` ou `created`. Quando a plataforma não consegue ver o app, imprime `unknown`.

<Callout>
  `unknown` sai com código `0`: a pergunta foi respondida, e a resposta é que a plataforma não sabe. Uma leitura que falha, por autenticação, erro de servidor ou rede, mantém o código de saída correspondente.
</Callout>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Fazer deploy de um app" icon="rocket" href="/pt/guides/deploy-an-app">
    O mesmo deploy pela API, para comparar.
  </Card>

  <Card title="Chaves de API" icon="key" href="/pt/guides/api-keys">
    Como as chaves funcionam e como protegê-las.
  </Card>

  <Card title="Ver logs" icon="file-lines" href="/pt/guides/view-logs">
    Onde encontrar a saída do seu app.
  </Card>

  <Card title="SDKs oficiais" icon="code" href="/pt/sdks/overview">
    TypeScript e Python, para chamar a API do seu código.
  </Card>
</CardGroup>