CLI do Zenovay

O CLI do Zenovay (@zenovay/cli) é um aplicativo de terminal para instalar, configurar e explorar o Zenovay Analytics direto do seu shell. Ele combina um assistente de instalação com IA e um painel TUI, para que você possa entregar analytics, observar eventos ao vivo e depurar a partir do mesmo lugar.

O CLI é uma ferramenta pública e voltada ao cliente. O gerenciamento de conta para cobrança e configurações de equipe continua acontecendo no painel em app.zenovay.com.

Instalação

macOS / Linux (curl)

curl -fsSL https://cli.zenovay.com/install.sh | sh

Windows (PowerShell)

iwr -useb https://cli.zenovay.com/install.ps1 | iex

Homebrew (macOS / Linux)

export HOMEBREW_GITHUB_API_TOKEN=$(gh auth token)   # o tap é privado
brew tap zenovay/zenovay
brew install zenovay/zenovay/zenovay

O tap do Homebrew fica em zenovay/homebrew-zenovay (repositório privado no GitHub). O Brew precisa de HOMEBREW_GITHUB_API_TOKEN para clonar o tap e baixar os assets de release — o caminho mais fácil é gh auth token se você já tiver o GitHub CLI instalado. Para deixar permanente, adicione a linha de export ao ~/.zshrc ou ~/.bashrc.

npm (qualquer plataforma com Node ≥ 20)

npm install -g @zenovay/cli

Após a instalação, verifique com:

zenovay --version

Modelo de confiança

Os binários são assinados com Ed25519 pelo par de chaves de release do Zenovay — os scripts de instalação e a fórmula do Homebrew se recusam a instalar se o SHA-256 não bater com o manifesto. Binários adulterados são sempre rejeitados.

Não participamos do Apple Developer Program, então os binários não são notarizados pela Apple; os scripts de instalação e a fórmula do Homebrew removem o atributo de quarentena do macOS Gatekeeper (xattr -d com.apple.quarantine) para que o binário rode sem o aviso "não pode ser aberto". Mesma postura de bun, deno e uv. A confiança vem de (a) você executar explicitamente curl … | sh ou brew install (consentimento informado) e (b) o pin de SHA-256 verificando que os bytes batem.

Se preferir o caminho de confiança nativo da plataforma, use a rota npm install -g — o npm oferece suas próprias provenance attestations para @zenovay/cli.

Múltiplas instalações

Se você instalar o CLI por mais de um caminho (npm + brew é o caso comum), o zenovay doctor aponta o conflito e indica o comando de limpeza correto:

zenovay doctor
# ⚠  Conflito de caminho de instalação
# Múltiplos binários zenovay detectados no PATH:
#   • /Users/you/.npm-global/bin/zenovay  [npm-global] (primeiro no PATH)
#   • /opt/homebrew/bin/zenovay  [brew]
# Escolha um e desinstale os outros para evitar divergência de versão:
#   npm uninstall -g @zenovay/cli
#   brew uninstall zenovay

Login

O CLI usa OAuth 2.0 device flow — seu navegador é o limite de confiança, e nenhuma senha de longa duração jamais passa pelo CLI.

zenovay login

O CLI imprime um curto user_code e abre seu navegador em app.zenovay.com/cli/authorize. Aprove a solicitação ali, escolha a equipe à qual o token deve ficar restrito, e o CLI conclui o login automaticamente.

Os tokens são armazenados em ~/.config/zenovay/auth.json com permissões 0600. Os refresh tokens são rotacionados a cada uso.

Para trocar de conta, execute zenovay logout e faça login novamente.

Trabalhando com várias equipes

Se sua conta pertence a mais de uma equipe, o CLI usa, por padrão, a equipe escolhida no login. Você pode sobrescrever essa escolha por comando:

zenovay events tail --team-id 6f3e…

Programaticamente (ao chamar diretamente a External API), passe o id da equipe como header:

X-Zenovay-Team-Id: 6f3e…

O endpoint GET /v1/cli/me retorna a lista completa de equipes às quais a chave atual tem acesso.

Comandos comuns

Execute zenovay <command> --help para ver todas as opções.

Anotações em gráficos

Marque deploys, releases, campanhas, incidentes e eventos personalizados em cada gráfico de série temporal do Zenovay direto do seu pipeline de CI.

zenovay annotation create --type=deploy --message="release v2.5"

Flags:

Limites do plano: Gratuito = 10 anotações / mês por time. Pro e superior são ilimitados.

Dedup: uma anotação do mesmo type dentro de 5 minutos de uma existente é rejeitada com HTTP 409 (código de saída do CLI 5). Protege contra pipelines de CI mal configurados que postariam o mesmo marcador de deploy duas vezes.

Exemplo do GitHub Actions

- name: Marcar deploy no Zenovay
  run: |
    zenovay annotation create \
      --type=deploy \
      --message="${{ github.event.head_commit.message }}" \
      --json
  env:
    ZENOVAY_API_TOKEN: ${{ secrets.ZENOVAY_CLI_TOKEN }}

As anotações também alimentam a triagem de incidentes de conversão: qualquer incidente aberto dentro de ±2 horas de uma anotação a lista como "mudança suspeita" no painel de detalhes do incidente.

Uso programático (External API)

Os mesmos tokens do CLI funcionam para chamadas diretas à External API. Veja o artigo de ajuda sobre Webhooks para entrega de eventos de saída e o artigo sobre Exportação do Log de Auditoria para arquivamento de conformidade.

curl https://api.zenovay.com/v1/cli/me \
  -H "Authorization: Bearer YOUR_CLI_API_KEY"

Toda resposta da API contém um header x-request-id — inclua-o em tickets de suporte para que possamos rastrear a chamada exata.

Resumo de planos e limites de taxa

Os recursos de IA do CLI (zenovay ai, o assistente de instalação com IA) são limitados pelo limite de comandos de IA. Comandos simples do CLI (sites, events tail, watch) só contam contra o limite de taxa da API.

Código-fonte e rastreamento de issues

O código-fonte do CLI é privado da equipe Zenovay, mas os binários publicados e o pacote npm são públicos. Pedidos de funcionalidades e relatos de bugs são bem-vindos em community.zenovay.com.