CLI de Zenovay

El CLI de Zenovay (@zenovay/cli) es una aplicación de terminal para instalar, configurar y explorar Zenovay Analytics desde tu shell. Combina un asistente de instalación con IA y un panel TUI para que puedas desplegar analíticas, observar eventos en vivo y depurar desde el mismo lugar.

El CLI es una herramienta pública orientada al cliente. La gestión de cuenta para facturación y configuración del equipo se sigue haciendo en el panel en app.zenovay.com.

Instalación

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)   # el tap es privado
brew tap zenovay/zenovay
brew install zenovay/zenovay/zenovay

El tap de Homebrew está en zenovay/homebrew-zenovay (repositorio privado de GitHub). Brew necesita HOMEBREW_GITHUB_API_TOKEN para clonar el tap y descargar los assets de release — la vía más sencilla es gh auth token si ya tienes GitHub CLI instalado. Para hacerlo permanente, añade la línea de export a ~/.zshrc o ~/.bashrc.

npm (cualquier plataforma con Node ≥ 20)

npm install -g @zenovay/cli

Tras la instalación, verifica con:

zenovay --version

Modelo de confianza

Los binarios están firmados con Ed25519 mediante el par de claves de release de Zenovay — los scripts de instalación y la fórmula de Homebrew rechazan instalar si el SHA-256 no coincide con el manifiesto. Los binarios manipulados se rechazan, siempre.

No participamos en el Apple Developer Program, así que los binarios no están notarizados por Apple; los scripts de instalación y la fórmula de Homebrew eliminan el atributo de cuarentena de macOS Gatekeeper (xattr -d com.apple.quarantine) para que el binario se ejecute sin el aviso de "no se puede abrir". La misma postura que bun, deno y uv. La confianza viene de (a) que tú ejecutes explícitamente curl … | sh o brew install (consentimiento informado), y (b) el SHA-256 anclado verifica que los bytes coinciden.

Si prefieres la vía de confianza nativa de la plataforma, usa la ruta de npm install -g — npm proporciona sus propias attestations de provenance para @zenovay/cli.

Múltiples instalaciones

Si instalas el CLI por más de una vía (npm + brew es el caso común), zenovay doctor señala el conflicto y te indica el comando de limpieza correcto:

zenovay doctor
# ⚠  Conflicto en la ruta de instalación
# Se han detectado múltiples binarios zenovay en PATH:
#   • /Users/you/.npm-global/bin/zenovay  [npm-global] (primero en PATH)
#   • /opt/homebrew/bin/zenovay  [brew]
# Elige uno y desinstala los demás para evitar deriva de versiones:
#   npm uninstall -g @zenovay/cli
#   brew uninstall zenovay

Inicio de sesión

El CLI usa OAuth 2.0 device flow — tu navegador es el límite de confianza, y ninguna contraseña de larga duración llega nunca al CLI.

zenovay login

El CLI imprime un breve user_code y abre tu navegador en app.zenovay.com/cli/authorize. Aprueba la solicitud allí, elige el equipo al que debe limitarse el token, y el CLI completa el inicio de sesión automáticamente.

Los tokens se almacenan en ~/.config/zenovay/auth.json con permisos 0600. Los refresh tokens rotan en cada uso.

Para cambiar de cuenta, ejecuta zenovay logout y vuelve a iniciar sesión.

Trabajar con varios equipos

Si tu cuenta pertenece a más de un equipo, el CLI usa por defecto el equipo seleccionado al iniciar sesión. Puedes sobrescribirlo por comando:

zenovay events tail --team-id 6f3e…

Programáticamente (al llamar directamente a la External API), pasa el id del equipo como encabezado:

X-Zenovay-Team-Id: 6f3e…

El endpoint GET /v1/cli/me devuelve la lista completa de equipos a los que tiene acceso la clave actual.

Comandos comunes

Ejecuta zenovay <command> --help para ver todas las opciones.

Anotaciones en gráficos

Marca despliegues, releases, campañas, incidentes y eventos personalizados en cada gráfico temporal de Zenovay desde tu pipeline de CI.

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

Flags:

Límites de plan: Free = 10 anotaciones / mes por equipo. Pro y superior son ilimitados.

Deduplicación: una anotación del mismo type dentro de los 5 minutos de una existente se rechaza con HTTP 409 (código de salida CLI 5). Protege contra pipelines de CI mal configurados que de otro modo publicarían el mismo marcador de despliegue dos veces.

Ejemplo de GitHub Actions

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

Las anotaciones también alimentan el triaje de incidentes de conversión: cualquier incidente abierto dentro de ±2 horas de una anotación la muestra como "cambio sospechoso" en el panel de detalle del incidente.

Uso programático (External API)

Los mismos tokens del CLI funcionan para llamadas directas a la External API. Consulta el artículo de ayuda de Webhooks para la entrega saliente de eventos y el artículo de Exportación del log de auditoría para el archivado de cumplimiento.

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

Cada respuesta de la API incluye un encabezado x-request-id — añádelo a los tickets de soporte para que podamos rastrear la llamada exacta.

Resumen de planes y límites de tasa

Las funciones de IA del CLI (zenovay ai, el asistente de instalación con IA) están limitadas por el cupo de comandos de IA. Los comandos simples del CLI (sites, events tail, watch) solo cuentan contra el límite de tasa de la API.

Código fuente y seguimiento de problemas

El código fuente del CLI es privado del equipo de Zenovay, pero los binarios publicados y el paquete de npm son públicos. Las solicitudes de funcionalidades y los reportes de bugs son bienvenidos en community.zenovay.com.