CLI de Deploy e Automação

A CLI da Zenifra permite listar projetos, criar recursos e disparar deploys a partir do terminal, scripts e pipelines.

Permissões necessárias

owner tem acesso completo. assistant, member e API Keys precisam dos grants correspondentes.

Esta página resume os comandos de deploy e automação. Para a referência completa da ferramenta, acesse CLI da Zenifra.

Use a CLI quando você quer operar a Zenifra sem abrir o console: criar um projeto, consultar o catálogo de planos, listar recursos, disparar deploys e acompanhar builds.

Começo rápido

npm install -g @zenifra/cli
zenifra auth login
zenifra whoami
zenifra projects --type http --page 1 --limit 15
zenifra create project
zenifra deploy --project <project-id> --branch main
zenifra deploy watch --project <project-id> --build <build-id>

Em projetos Git, zenifra deploy dispara a build e retorna build_id. Em seguida, zenifra deploy watch acompanha status e logs incrementais até o fim.

Para ver todos os comandos disponíveis:

zenifra --help
zenifra help create project

Comandos incompletos como zenifra deploy, zenifra deploy watch e zenifra builds abrem a ajuda específica do próprio comando.

Autenticação

Login de usuário

Use login de usuário para navegar entre organizações:

zenifra auth login
zenifra orgs
zenifra org set

zenifra auth login usa o fluxo tradicional de email, senha e verificação. Esse modo é indicado para uso interativo no terminal.

Login OAuth

Use OAuth quando quiser autenticar pelo navegador:

zenifra auth login --oauth
zenifra auth login --oauth --no-browser

O primeiro comando abre o navegador automaticamente. Com --no-browser, a CLI mostra o endereço para abrir manualmente. Nos dois casos, o navegador e a CLI precisam estar na mesma máquina: o retorno OAuth é concluído por um callback loopback local. Se não houver uma sessão gráfica nessa máquina ou não for possível concluir o callback local, use uma API key da organização no ambiente de execução.

API key para automação

Para CI/CD e jobs server-side, crie uma API key da organização e use:

export ZENIFRA_API_KEY=znf_sua_chave
zenifra projects --type http --page 1 --limit 15
zenifra deploy --project <project-id> --branch main

Também é possível salvar a chave na sessão local:

zenifra auth api-key --key znf_sua_chave

API keys já carregam a organização vinculada. Por isso, comandos de automação não exigem org set.

Criar projeto pelo terminal

Rode zenifra create project sem flags quando quiser seguir o wizard interativo. Ele pergunta os campos necessários, mostra exemplos e deixa explícito quais valores precisam ser informados.

$ zenifra create project

Wizard interativo de criacao de projeto Zenifra
Digite ? para ajuda detalhada em qualquer campo.

? Nome do projeto: app-api
? Descricao: API principal do produto
? Tipo do projeto: http
? Plano: free
? Modo de pagamento: hourly
? Origem do deploy HTTP: github
? Porta da aplicacao: 3000
? Quantidade de instancias: 1
? Deseja adicionar variaveis de ambiente? sim
? Nome da env: NODE_ENV
? Valor da env: production
? Deseja adicionar mais um item? nao
? Exposicao HTTP: public
? Repository owner: minha-org
? Repository name: app-api
? Branch: main
? Runtime: nodejs
? Versao do runtime: 24
? Modo de deploy GitHub: branch
? Start command: npm start
? Pre build command:
? Build command: npm run build

Resumo da criacao
  projeto: app-api | plano: free | pagamento: hourly
  tipo: http
  descricao: API principal do produto
  http: exposicao public | porta 3000 | instancias 1 | storage 1Gi (efemero)
  github: minha-org/app-api@main | runtime nodejs@24
? Confirmar criacao do projeto: sim

Campo    Valor
-------  --------------------------------------
Projeto  507f1f77bcf86cd799439012
Dominio  https://app-api.clients.zenifra.com

O comando acima é uma simulação do fluxo. As perguntas variam conforme o plano: no Free, o wizard não pergunta armazenamento persistente, auto-scaling nem subdomínio personalizado. O wizard oferece as origens github e oci; para uma origem Forgejo, use --config com source e build, como no exemplo abaixo. Os valores reais devem refletir seu repositório, plano, porta, runtime e variáveis. A URL retornada pelo comando é a fonte de verdade para acessar o projeto; não construa uma URL supondo um domínio padrão.

Exemplos comuns

Listar projetos HTTP:

zenifra projects --type http --page 1 --limit 15

A listagem de projetos é paginada por padrão com 15 itens por página. Para navegar, use --page <n>; para automações que precisam de outro tamanho, use --limit <n>.

Criar projeto a partir de um arquivo de configuração:

zenifra create project \
  --name app-api \
  --plan free \
  --payment-mode hourly \
  --config @http-project.json

Para uma origem Git, o arquivo de configuração usa source e build. Os identificadores abaixo são exemplos: substitua-os pelos IDs retornados pela conexão e pela seleção de repositório da organização.

{
  "type_project": "http",
  "exposure": "public",
  "source": {
    "connection_id": "connection-id-from-console",
    "repository_id": "repository-id-from-connection",
    "branch": "main",
    "auto_deploy": true
  },
  "build": {
    "runtime": "nodejs",
    "version": "24",
    "start_command": "npm start",
    "pre_build_command": null,
    "build_command": "npm run build"
  },
  "port": 3000
}

Não inclua um token de repositório no arquivo de projeto. Configure conexões de origem pelo fluxo seguro de conexão da organização. Para Forgejo, consulte Deploy a partir do Forgejo e a referência de conexões Git.

Em APIs mais antigas, comprovar que um projeto existente usa uma origem GitHub pode exigir project.read. A CLI não interpreta uma resposta de acesso negado como confirmação da origem nem tenta uma rota alternativa. Forgejo requer uma API que anuncie o contrato de origem Git compatível.

No arquivo de configuração de projetos HTTP, informe exposure: "public" para criar rota/domínio público ou exposure: "private" para manter a aplicação sem exposição na internet.

Depois da criação, altere a exposição com:

zenifra project exposure set --project <project-id> --exposure public
zenifra project exposure set --project <project-id> --exposure private

Use private para automações, jobs internos e aplicações que não precisam receber tráfego público.

Disparar deploy:

zenifra deploy --project <project-id> --branch main

Acompanhar esse build:

zenifra deploy watch --project <project-id> --build <build-id>

Reabrir logs de um build específico:

zenifra builds logs --project <project-id> --build <build-id>
zenifra builds logs --project <project-id> --build <build-id> --follow

Listar builds já existentes:

zenifra builds --project <project-id>

Use builds quando você precisa descobrir build_id. Use deploy watch quando já tem um build específico para acompanhar.

As entradas detalhadas de logs usam a fonte event e preservam a etapa e a sequência da build. Se só houver um diagnóstico final, a fonte summary informa que os eventos detalhados não estavam disponíveis para aquela build.

Consultar planos antes de criar:

zenifra plans --type http

A saída para pessoas lista as capacidades disponíveis no plano, como logs, métricas, healthcheck, auto-scaling, subdomínio personalizado e acesso de rede. Para automações, use zenifra plans --type http --json: o objeto capabilities retorna essas disponibilidades como valores booleanos. Consulte o plano antes de criar o projeto, porque as capacidades efetivas dependem do plano retornado.

Identidade e ciclo de vida do projeto

Veja a identidade segura da sessão e a organização selecionada:

zenifra whoami
zenifra whoami --json

O formato legível mostra nome do perfil, base da API, modo de autenticação, organização selecionada e, quando disponível, o nome público da organização. O formato JSON entrega os mesmos dados para scripts e nunca mostra credenciais.

Pare, retome ou exclua um projeto pelo identificador retornado pela criação ou pela listagem:

zenifra project stop --project <project-id>
zenifra project resume --project <project-id>
zenifra project delete --project <project-id> --yes

stop e resume consultam o projeto depois da operação para mostrar o estado confirmado. A exclusão exige --yes, inclusive em automações, para deixar a intenção destrutiva explícita. Todos os três comandos aceitam --json quando a saída será processada por outro programa.

Segurança

• use ZENIFRA_API_KEY em secrets do provedor de CI;
• configure IP allowlist quando o runner tem IP fixo;
• conceda apenas as permissões necessárias;
• rotacione e revogue chaves antigas.

Próximos passos

• CLI da Zenifra
• API Keys da Organização
• Implantação via GitHub
• Automático por branch