CLI da Zenifra

A zenifra-cli é a interface oficial de linha de comando da Zenifra. Ela permite operar a plataforma pelo terminal, scripts e pipelines sem depender do console web para tarefas repetitivas.

Use a CLI para autenticar, alternar perfis, consultar catálogos de planos, criar projetos, listar recursos, disparar deploys, acompanhar builds, ler logs, ajustar variáveis de ambiente e consultar métricas.

Instalação

Instale o pacote pelo npm:

npm install -g @zenifra/cli
zenifra --help

Cada comando possui uma ajuda específica com exemplos de uso e saída esperada:

zenifra help create project
zenifra plans --help
zenifra deploy watch --help

Use essa ajuda quando precisar confirmar flags aceitas antes de automatizar um fluxo em CI/CD.

Se você rodar um comando incompleto, como zenifra deploy, zenifra deploy watch ou zenifra builds, a CLI abre a ajuda específica do próprio comando em vez de retornar apenas uma mensagem curta de erro.

Uso com agentes de código

Se você trabalha com um agente de código, também pode usar o plugin oficial da Zenifra para disponibilizar a CLI diretamente na sua ferramenta. Ele é uma opção para fluxos no Codex, Claude Code, OpenCode e outras ferramentas compatíveis.

O plugin permite que o agente use os mesmos comandos e perfis da zenifra-cli no contexto da sua tarefa. Continue usando as credenciais e permissões adequadas para cada projeto e organização.

Consulte o repositório do plugin para visualizar a documentação, os requisitos e as instruções de instalação:

Plugin Zenifra para agentes de código

Autenticação

Use login de usuário quando estiver trabalhando de forma interativa e precisar navegar entre organizações:

zenifra auth login
zenifra orgs
zenifra org set

Esse modo é indicado para uso local, porque a conta de usuário pode participar de múltiplas organizações.

API key para automação

Use API key da organização para scripts, runners e pipelines:

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 no perfil local ativo:

zenifra auth api-key --key znf_sua_chave

API keys já carregam a organização vinculada. Por isso, comandos de automação como projects, deploy, builds e deployments não exigem org set. Comandos pessoais como orgs e org set continuam exigindo zenifra auth login.

Perfis e ambientes

A CLI trabalha com perfis locais para separar credenciais, descrições e API base:

zenifra profile list
zenifra profile add --name prod --description Producao --api-base https://api.zenifra.com/v1 --mode api-key --key znf_sua_chave
zenifra profile use prod
zenifra profile show

Variáveis de ambiente podem sobrescrever a configuração do perfil apenas durante uma execução:

ZENIFRA_API_URL=https://api.zenifra.com/v1 zenifra projects --type http --page 1 --limit 15
ZENIFRA_CONFIG_DIR=/tmp/zenifra-cli zenifra profile list

Use ZENIFRA_CONFIG_DIR em testes e validações temporárias quando não quiser alterar a sessão real da máquina.

Consultar planos

Antes de criar um projeto, consulte os catálogos públicos de HTTP, banco de dados, serviços gerenciados e armazenamento:

zenifra plans
zenifra plans --type http
zenifra plans --type database
zenifra plans --type valkey
zenifra plans --type storage --json

zenifra plans não exige autenticação. A saída humana mostra tabelas por categoria, enquanto --json retorna dados estruturados para scripts.

Criar projetos

Para criar um projeto com wizard interativo, rode:

zenifra create project

O wizard pergunta os campos necessários, mostra exemplos e deixa claro quais valores precisam ser informados. A CLI não assume valores default para plano ou modo de pagamento; escolha esses valores a partir do catálogo retornado por zenifra plans.

Para automação, use um arquivo de configuração:

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

O comando também aceita configurações para projetos HTTP com GitHub ou imagem OCI, projetos PostgreSQL e MariaDB e serviços Valkey.

Configurações Valkey

Consulte primeiro zenifra plans --type valkey. O card escolhido no Console e o perfil enviado pela CLI precisam concordar. O plano comercial também identifica o perfil: db-* para Chave‑Valor, cache-* para Cache e queue-* para Filas. A versão suportada neste exemplo é 9.1.1.

Salve cada bloco em um arquivo JSON e passe-o com --config @arquivo.json.

Chave‑Valor é persistente e usa armazenamento:

{
  "type_project": "valkey",
  "profile": "key_value",
  "version": "9.1.1",
  "storage": {
    "persistent": true,
    "capacity": 5
  }
}

zenifra create project --name sessions --plan db-basic --payment-mode monthly --config @key-value.json

Cache é descartável e não envia armazenamento:

{
  "type_project": "valkey",
  "profile": "cache",
  "version": "9.1.1"
}

zenifra create project --name product-cache --plan cache-basic --payment-mode monthly --config @cache.json

Filas usam armazenamento persistente para Streams e consumer groups:

{
  "type_project": "valkey",
  "profile": "queue",
  "version": "9.1.1",
  "storage": {
    "persistent": true,
    "capacity": 5
  }
}

zenifra create project --name email-workers --plan queue-basic --payment-mode hourly --config @queue.json

Não informe imagem, runtime, porta, instâncias ou regras de IP. O acesso Valkey é público em IPv4 e protegido por TLS e autenticação; consulte o overview Valkey, o guia de Banco de Dados Chave‑Valor, Cache, Filas e a referência REST. Use zenifra projects --type valkey, zenifra valkey status, zenifra valkey connection e zenifra valkey credentials rotate para operar o serviço.

Em projetos HTTP, informe config.exposure:

public: cria rota pública e domínio.
private: cria o projeto sem domínio público, indicado para automações e rotinas internas.

Operar projetos

Depois que o projeto existe, use a CLI para consultar estado, URL, logs, métricas, variáveis e instâncias:

zenifra projects --type http --page 1 --limit 15
zenifra project info --project <project-id>
zenifra project url --project <project-id>
zenifra project logs --project <project-id> --instance <instance-id>
zenifra project metrics --project <project-id> --instance <instance-id>
zenifra project envs --project <project-id>
zenifra project instances --project <project-id>
zenifra project autoscaling --project <project-id>
zenifra project exposure set --project <project-id> --exposure private

zenifra projects usa paginação por padrão com 15 projetos por página. Use --page <n> para navegar e --limit <n> para ajustar o tamanho da página quando estiver automatizando listagens.

Para variáveis de ambiente:

zenifra project env add --project <project-id> --name NODE_ENV --value production
zenifra project env update --project <project-id> --name NODE_ENV --value staging
zenifra project env remove --project <project-id> --name NODE_ENV

Valores de variáveis são mascarados por padrão, inclusive em saídas JSON. Use flags para exibir valores completos apenas quando isso for necessário e seguro.

Para alterar se um projeto HTTP fica exposto na internet após a criação:

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

public cria ou restaura a rota pública e domínio. private remove a rota pública, subdomínio da Zenifra e domínios personalizados.

Para ativar ou desativar auto-scaling em projetos HTTP:

zenifra project autoscaling --project <project-id>
zenifra project autoscaling set --project <project-id> --min 2 --max 8 --cpu 70 --memory 80
zenifra project autoscaling disable --project <project-id>
zenifra project autoscaling events --project <project-id> --direction scale_up --page 1 --limit 10

Com auto-scaling ativo, altere a faixa mínima/máxima pelo comando de autoscaling. A alteração manual de instâncias fica bloqueada até desativar a feature. Use events para consultar o histórico auditável de aumento e redução de instâncias.

Deploys e builds

Dispare um deploy manual pela branch configurada:

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

zenifra deploy dispara o build/deploy GitHub e retorna um build_id. Use esse identificador para acompanhar a execução em tempo real.

Liste builds e deploys:

zenifra builds --project <project-id>
zenifra deployments --project <project-id>

Use zenifra builds para descobrir quais builds existem, com status, branch e histórico paginado.

Acompanhe um build até terminar:

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

Esse fluxo é útil para pipelines que precisam aguardar o resultado do build antes de executar validações externas.

Na prática, zenifra deploy watch faz polling do status e imprime os logs incrementais do build até o estado terminal.

Para reabrir os logs de um build específico, com ou sem acompanhamento contínuo:

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

Diferença entre os comandos:

zenifra project logs: logs da aplicação em execução
zenifra builds logs: logs do pipeline de build GitHub
zenifra deploy watch: status + logs incrementais de um build específico

Segurança

Armazene ZENIFRA_API_KEY em secrets do provedor de CI.
Prefira variável de ambiente em runners efêmeros, sem gravar sessão local.
Configure IP allowlist quando a automação tiver origem fixa.
Conceda apenas as permissões necessárias para o job.
Rotacione e revogue chaves antigas.
Evite imprimir valores completos de variáveis sensíveis em logs de CI.