CLI da Zenifra

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

Instalação

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

Cada comando tem ajuda própria com flags, exemplos e saída esperada:

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

Se você rodar um comando incompleto, como zenifra deploy ou zenifra builds, a CLI abre a ajuda do próprio comando. Todos os comandos de listagem aceitam --json, útil em scripts.

Permissões necessárias

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

Uso com agentes de código

Agentes de código com acesso ao terminal podem usar a CLI diretamente. Para o Codex, o plugin oficial da Zenifra orienta o agente a usar os mesmos comandos e perfis da CLI, com as credenciais e permissões que você configurou.

• Plugin Zenifra para Codex

Para apenas consultar dados em um cliente de IA, o Zenifra MCP oferece acesso OAuth somente leitura. Use a CLI para operações no terminal e o MCP para consultas dentro do cliente de IA.

Autenticação e perfis

Login de usuário

Indicado para uso interativo, quando você navega entre organizações:

zenifra auth login
zenifra orgs
zenifra org set
zenifra whoami

zenifra whoami mostra o perfil ativo, a API e a organização selecionada, sem exibir credenciais.

Login pelo navegador (OAuth)

Abre o Console para você entrar, concluir a verificação de segurança e aprovar o acesso da CLI:

zenifra auth login --oauth
zenifra auth login --oauth --read-only
zenifra auth login --oauth --no-browser

• --read-only solicita somente leitura; as permissões da sua organização continuam valendo.
• --no-browser mostra o endereço para abrir manualmente no navegador da mesma máquina.
• --read-only e --no-browser exigem --oauth.
• O login aguarda até três minutos; use Ctrl+C para cancelar. Os tokens ficam no perfil local privado e são renovados automaticamente.

Sem --oauth, auth login usa e-mail, senha e verificação.

API key para automação

Use uma API key da organização em 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

Ou salve a chave no perfil ativo:

zenifra auth api-key --key znf_sua_chave

API keys já carregam a organização vinculada, então projects, deploy, builds e deployments não exigem org set. Comandos pessoais como orgs e org set exigem zenifra auth login.

Sair e revogar

zenifra auth logout            # remove só a autenticação local
zenifra auth logout --revoke   # também revoga a conexão do perfil

--revoke exige um perfil autenticado por login e não revoga API keys.

Perfis e ambientes

Perfis locais separam credenciais, descrição 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
zenifra profile edit prod --description "Producao principal"
zenifra profile remove prod

auth login --profile <nome> e auth api-key --profile <nome> criam ou atualizam outro perfil e o tornam ativo. Não reutilize um token em outra API: crie outro perfil.

Variáveis de ambiente sobrescrevem o perfil apenas durante a execução:

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

ZENIFRA_API_KEY tem prioridade sobre a credencial do perfil. Use ZENIFRA_CONFIG_DIR em testes para não alterar a sessão real.

Organizações

zenifra orgs
zenifra org set
zenifra org set --org <organization-id>

Consultar planos

Antes de criar um projeto, compare os catálogos públicos. O comando não exige autenticação:

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

A saída mostra tabelas por categoria; para planos HTTP, inclui as capacidades disponíveis (logs, métricas, verificação de saúde, auto-scaling, subdomínio personalizado e acesso de rede). Use --json para scripts.

Criar projetos

Sem argumentos, a CLI abre um wizard interativo que pergunta os campos, mostra exemplos e a documentação relacionada:

zenifra create project

O wizard cobre projetos HTTP (imagem ou GitHub), PostgreSQL, MariaDB, Valkey (Chave‑Valor, Cache e Filas) e Jobs agendados. ClickHouse e projetos HTTP com origem Git de uma conexão usam o modo não interativo com --config.

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

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

A CLI não assume --plan nem --payment-mode (exceto Jobs, que usam per_minute); escolha-os em zenifra plans.

O --config aceita estes valores de type_project:

Valores de payment_mode: hourly, monthly, yearly e per_minute (somente Jobs). 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.

Exemplos de configuração prontos estão na pasta examples/ do repositório da CLI (http-project.json, http-git-project.json, postgresql-project.json, clickhouse-project.json, job-project.json, entre outros).

Deploy por imagem

zenifra project image set --project <project-id> --image ghcr.io/zenifra/app:1.2.0

Prefira sempre uma tag de versão fixa em vez de latest.

Deploy por Git

Projetos podem usar uma origem Git de um provedor suportado (GitHub ou Forgejo). Uma pessoa proprietária da organização cria a conexão no Console; a CLI lista e usa conexões existentes e nunca solicita nem exibe credenciais do provedor.

Confira provedores, runtimes e conexões, resolva o repositório pelo caminho e liste as branches:

zenifra git providers
zenifra git runtimes
zenifra git connections
zenifra git repositories resolve --connection <connection-id> --path equipe/aplicacao
zenifra git branches --connection <connection-id> --repository <repository-id>

O ID retornado por resolve pertence àquela conexão. Use os IDs em config.source e config.build ao criar o projeto (veja examples/http-git-project.json):

zenifra create project --name api-web --plan basic --payment-mode hourly --config @examples/http-git-project.json

Consulte e altere a origem e o modo de deploy do projeto:

zenifra project source --project <project-id>
zenifra project source branches --project <project-id>
zenifra project source deploy-settings set --project <project-id> --mode branch
zenifra project source deploy-settings set --project <project-id> --mode tag --tag-pattern "v*"
zenifra project source deploy-settings set --project <project-id> --mode release --tag-pattern "v*" --include-prereleases true

Os modos são manual, branch, tag e release. tag e release exigem --tag-pattern (curingas * e ?); --include-prereleases só vale em release e o padrão é false. Evite alterar a origem ao mesmo tempo pelo Console ou por outro cliente.

Projetos com configuração GitHub legada continuam usando zenifra project github e zenifra project github deploy-settings set, com os mesmos modos.

Disparar e acompanhar builds

zenifra deploy --project <project-id> --branch main
zenifra deploy watch --project <project-id> --build <build-id>
zenifra builds --project <project-id>
zenifra builds logs --project <project-id> --build <build-id> --follow
zenifra deployments --project <project-id>

zenifra deploy dispara o build/deploy Git e retorna um build_id. deploy watch acompanha o status e imprime os logs incrementais até o estado final, útil em pipelines. Diferença entre os logs:

• zenifra project logs: aplicação em execução
• zenifra builds logs: pipeline de build Git
• zenifra deploy watch: status + logs de um build específico

Configurar projetos

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

Variáveis de ambiente (valores mascarados por padrão, inclusive em --json):

zenifra project envs --project <project-id>
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

Use --show-values em envs apenas quando for necessário e seguro.

Exposição, instâncias e auto-scaling (projetos HTTP):

zenifra project exposure set --project <project-id> --exposure private
zenifra project instances set --project <project-id> --count 3
zenifra project autoscaling set --project <project-id> --min 2 --max 8 --cpu 70 --memory 80
zenifra project autoscaling disable --project <project-id>

private remove a rota pública, o subdomínio da Zenifra e os domínios personalizados; public os restaura. Com auto-scaling ativo, ajuste a faixa pelo comando de autoscaling: a alteração manual de instâncias fica bloqueada até desativá-lo.

Verificação de saúde:

zenifra project healthcheck get --project <project-id>
zenifra project healthcheck set --project <project-id> --path /health
zenifra project healthcheck disable --project <project-id>

Observar projetos

zenifra projects --type http --page 1 --limit 15
zenifra project logs --project <project-id> --instance <instance-id>
zenifra project metrics --project <project-id> --instance <instance-id>
zenifra project metrics capabilities --project <project-id>
zenifra project network --project <project-id> --view summary
zenifra project healthcheck failures --project <project-id>
zenifra project autoscaling events --project <project-id> --direction scale_up
zenifra project billing usage --project <project-id> --from 2026-06-01T00:00:00Z --limit 20

• zenifra projects pagina com 15 itens por página; ajuste com --page e --limit.
• project metrics capabilities informa o nível de acesso e os grupos de métricas disponíveis antes de buscar um snapshot; valores ausentes aparecem como indisponivel.
• project network --view aceita summary, status-codes, routes, user-agents, request-events e source-ips.
• autoscaling events aceita --direction scale_up|scale_down, --from e --to; billing usage aceita --from e --to em formato ISO.

Jobs agendados

Consulte os planos com zenifra plans --type job e crie o Job com uma imagem pronta e um cron de cinco campos em UTC. Jobs são cobrados por minuto inteiro e não usam origem Git, exposição, porta nem instâncias:

zenifra create project --name nightly-report --plan job-basic --payment-mode per_minute --config @examples/job-project.json

Acompanhe as execuções:

zenifra project runs --project <project-id> --page 1 --limit 20
zenifra project runs logs --project <project-id> --run <run-id>
zenifra project runs cancel --project <project-id> --run <run-id>

runs cancel cancela apenas a execução selecionada e aguarda até 30 segundos pela finalização segura; o cron continua agendando novas execuções. Use zenifra project stop para pausar o projeto e interromper execuções futuras.

Serviços de dados

PostgreSQL, MariaDB e ClickHouse

zenifra create project --name app-db --plan db-basic --payment-mode monthly --config @examples/postgresql-project.json
zenifra create project --name app-db --plan db-basic --payment-mode monthly --config @examples/mariadb-project.json
zenifra create project --name events --plan analytics-starter --payment-mode hourly --config @examples/clickhouse-project.json

O wizard e os exemplos não pedem usuário, senha nem nome do banco.

Valkey

Consulte primeiro zenifra plans --type valkey. O plano identifica o perfil: db-* para Chave‑Valor, cache-* para Cache e queue-* para Filas. A versão suportada neste exemplo é 9.1.1.

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, Banco de Dados Chave‑Valor, Cache, Filas e a referência REST.

Para operar o serviço:

zenifra projects --type valkey
zenifra valkey status --project <project-id>
zenifra valkey connection --project <project-id>
zenifra valkey credentials rotate --project <project-id> --wait
zenifra valkey credentials status --project <project-id> --operation <operation-id>

A conexão consultada é mascarada; a credencial completa aparece apenas na criação ou em uma rotação concluída. Para salvá-la em arquivo privado, sem exibi-la na saída:

zenifra valkey credentials rotate --project <project-id> --wait --connection-file /caminho/privado/conexao.txt

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.

Próximos passos

• API Keys da Organização
• Implantação via GitHub
• CLI de Deploy e Automação
• Observabilidade
• Checklist de produção