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.

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

zenifra plans
zenifra plans --type http
zenifra plans --type database
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, além de projetos PostgreSQL e MariaDB.

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

Deploys e builds

Dispare um deploy manual pela branch configurada:

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

Liste builds e deploys:

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

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.

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.