CLI - Hyze Cloud

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.

Instalação

Node 18+ ou Bun, um comando.

Primeiros passos

Do login ao app no ar.

Instalação

npm install -g @hyze-cloud/cli
# ou
bun add -g @hyze-cloud/cli

hyze --version

Roda em Node 18+ e Bun.

Primeiros passos

Guarde sua API key

Crie uma chave no dashboard em Settings → Developer e guarde com hyze login. A CLI confere a chave contra a API antes de salvar.

hyze login

Veja o que existe no workspace

hyze projects

Faça deploy

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

Confira o que está no ar

hyze status my-api
hyze logs my-api --follow

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

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`

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

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

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

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.

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.

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.

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.

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.

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.

Próximos passos

Fazer deploy de um app

O mesmo deploy pela API, para comparar.

Chaves de API

Como as chaves funcionam e como protegê-las.

Ver logs

Onde encontrar a saída do seu app.

SDKs oficiais

TypeScript e Python, para chamar a API do seu código.

Instalação

Primeiros passos

​Instalação

​Primeiros passos

​Comandos

​Tela interativa

​Autenticação e configuração

​Arquivos de configuração

​Variáveis de ambiente

​Opções globais

​Usar em scripts

​Deploy

​O que sobe no ZIP

​Logs

​Erros e códigos de saída

​O estado unknown

​Próximos passos

Fazer deploy de um app

Chaves de API

Ver logs

SDKs oficiais

Instalação

Primeiros passos

Comandos

Tela interativa

Autenticação e configuração

Arquivos de configuração

Variáveis de ambiente

Opções globais

Usar em scripts

Deploy

O que sobe no ZIP

Logs

Erros e códigos de saída

O estado `unknown`

Próximos passos