Pular para o conteúdo principal

CLI

Um binário sem dependências, para macOS, Linux e Windows.

Instalar​

Baixe em zero.nnumbers.com.br/downloads, confira o checksum e coloque no PATH:

curl -fsSLO https://zero.nnumbers.com.br/downloads/zero-darwin-arm64.tar.gz
curl -fsSLO https://zero.nnumbers.com.br/downloads/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing
tar -xzf zero-darwin-arm64.tar.gz
sudo mv zero /usr/local/bin/
zero version

No Linux, use sha256sum -c. No Windows, extraia o .zip e coloque zero.exe numa pasta do PATH.

Autenticar​

zero auth login

A CLI pergunta o seu e-mail e abre a aprovação no navegador: o terminal mostra um link e um código curto, você confere o código na tela de login da sua empresa e aprova — com o MFA e as políticas dela. O e-mail só descobre para onde mandar o login; quem autentica é o provedor. A sessão fica gravada cifrada, com a chave no chaveiro do sistema (onde não há chaveiro, num arquivo só do seu usuário), e renova sozinha.

Para máquina (CI, contêiner), há dois caminhos: ZERO_TOKEN no ambiente, que vale acima de tudo e não é gravado, ou um token de serviço lido da entrada padrão — nunca de um argumento, que fica no histórico do shell e na lista de processos:

echo "$TOKEN" | zero auth login --token
zero auth status    # quem sou eu, e onde
zero auth logout    # descarta a credencial

Se sua conta participa de mais de uma organização:

zero orgs list
zero orgs use <organização>

A jornada​

PROJ=$(zero projects create loja)     # o ambiente production nasce junto
zero projects get "$PROJ"             # mostra o identificador do ambiente
zero source set "$PROJ" --provider github --repo voce/loja --ref main
SVC=$(zero services create web --env <ambiente> --subdir apps/web)
zero deploy "$SVC"

projects create e services create imprimem só o identificador em stdout — de propósito, para encadear em scripts. As explicações vão para stderr.

O repositório é do projeto. zero source set configura a origem; o serviço declara só a pasta que constrói (--subdir). --repo aceita dono/repo, a URL completa ou o endereço SSH; --provider (github, gitlab ou bitbucket) é obrigatório quando o endereço não diz o host. Para repositório privado, acrescente --token: o token é lido da entrada padrão, nunca de um argumento. --repo em services create ou em deploy é recusado, com a frase que aponta para zero source set.

Criar um serviço não publica, e a CLI diz isso.

Publicar​

zero deploy "$SVC"
zero deploy "$SVC" --ref release/2026-09   # outra branch ou tag, só desta vez

zero deploy acompanha a publicação ao vivo e termina com código de saída 0 quando ela fica pronta e 1 quando falha — mostrando o motivo, como HEALTH_CHECK_FAILED quando a aplicação iniciou mas não respondeu. Os motivos estão em Estados da publicação.

Operar​

zero status <projeto>          # ambientes, serviços e o que está no ar
zero logs --follow             # a saída da aplicação, ao vivo
zero logs <deployment> --build # a saída do build
zero releases <serviço>        # o histórico imutável de ativações
zero artifacts <serviço>       # as versões construídas, com o digest de cada uma

Promover​

zero promote web-prod --from web-preview

Ver Promover entre ambientes.

Excluir um projeto​

zero projects delete <projeto> --reason "piloto encerrado" --yes

Sem --yes, a CLI pede o nome do projeto, digitado — e recusa quando a entrada não é um terminal: em script, --yes é a confirmação explícita. A exclusão é acompanhada até o fim: código 0 quando termina, 1 quando falha, e repetir o comando tenta de novo. O que muda e o que fica está em Excluir o projeto.

Usuários e acesso​

zero users list                      # as pessoas do provedor de identidade, com o acesso de cada uma
zero users search carolina           # por nome, e-mail ou nome de usuário
zero access grant <id> --role operator
zero access update <id> --role member --project <space>
zero access revoke <id>              # a conta no provedor continua existindo
zero users create --email ana@empresa.com.br --first-name Ana --last-name Souza --role admin
zero users resend-password-setup <id>

Conceder vale na hora, sem convite nem aceite. create não tem opção de senha: a conta nasce sem senha e o provedor de identidade envia à pessoa o e-mail oficial para defini-la. O <id> é o identificador da pessoa no provedor, que zero users list mostra. Detalhes em Usuários e acesso.

Rede entre projetos​

zero networks create pagamentos
zero networks attach <ambiente> --network pagamentos   # um ambiente de cada projeto
zero networks get pagamentos                           # quem está na rede
zero services internal-name <serviço> api              # imprime api.zero.internal
zero networks grant pagamentos --from <projeto> --to <serviço> --wait
zero networks grants pagamentos                        # as permissões, de serviço e de entrada interna
zero networks revoke pagamentos <permissão>
zero projects network <projeto>                        # quem chega, para onde sai, os endereços internos
zero environments network <ambiente>                   # a rede do ambiente e o estado das regras

A rede e a entrada interna vão pelo nome ou pelo identificador. A permissão usa a porta do serviço; --port só é aceito se for ela.

Projeto sem endereço na internet:

zero projects create cobranca --internal
zero projects exposure <projeto> internal              # ou public, para voltar

Entradas internas do Gateway, com caminhos para serviços da rede:

zero entries create api --network pagamentos           # api.zero.internal
zero entries add-route api --service <serviço> --path /v1 --strip-prefix
zero entries add-route api --service <outro-serviço> --path /saude --exact
zero entries routes api
zero entries grant api --from <projeto>
zero entries grants api
zero entries remove-route api <rota>
zero entries revoke api <permissão>
zero entries delete api

Com um Gateway só na organização, a CLI o usa; com mais de um, diga qual com --gateway.

Revogar, tirar da rede, remover caminho, mudar a exposição, tirar o nome e excluir pedem o nome do alvo, digitado — e recusam quando a entrada não é um terminal: em script, --yes é a confirmação explícita. --wait espera a regra ser aplicada e sai com código 1 se o prazo vencer (--timeout, padrão 5m). Ver Rede entre projetos.

Domínios​

Não há comando de CLI para domínios. A troca de endereço e as zonas de domínio próprio ficam no console e na API.

Detalhes que importam​

  • --json em quase todo comando, para consumo por script.
  • --detach no deploy e no promote devolve o controle imediatamente; sem ele a CLI acompanha ao vivo até o desfecho.
  • Ctrl-C durante um acompanhamento cancela o acompanhamento, não a publicação — e fecha a conexão de forma limpa.
  • O código de saída é diferente de zero quando a operação falha, então zero deploy && zero promote é seguro.