CLI Zenovay

Le CLI Zenovay (@zenovay/cli) est une application terminal pour installer, configurer et explorer Zenovay Analytics depuis votre shell. Il associe un assistant d'installation IA à un tableau de bord TUI afin que vous puissiez livrer des analytics, observer les événements en direct et déboguer depuis le même endroit.

Le CLI est un outil public, destiné aux clients. La gestion du compte pour la facturation et les paramètres d'équipe se fait toujours dans le tableau de bord sur app.zenovay.com.

Installation

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)   # le tap est privé
brew tap zenovay/zenovay
brew install zenovay/zenovay/zenovay

Le tap Homebrew se trouve sur zenovay/homebrew-zenovay (dépôt GitHub privé). Brew a besoin de HOMEBREW_GITHUB_API_TOKEN pour cloner le tap et télécharger les artefacts de release — le plus simple est gh auth token si vous avez déjà GitHub CLI installé. Pour rendre cela permanent, ajoutez la ligne export à ~/.zshrc ou ~/.bashrc.

npm (toute plateforme avec Node ≥ 20)

npm install -g @zenovay/cli

Après l'installation, vérifiez avec :

zenovay --version

Modèle de confiance

Les binaires sont signés Ed25519 par la paire de clés de release Zenovay — les scripts d'installation et la formule Homebrew refusent l'installation si la SHA-256 ne correspond pas au manifeste. Les binaires altérés sont systématiquement rejetés.

Nous ne participons pas au programme Apple Developer ; les binaires ne sont donc pas notarisés Apple. Les scripts d'installation et la formule Homebrew suppriment l'attribut de quarantaine macOS Gatekeeper (xattr -d com.apple.quarantine) afin que le binaire s'exécute sans le message « ne peut pas être ouvert ». Même posture que bun, deno et uv. La confiance vient (a) du fait que vous exécutez explicitement curl … | sh ou brew install (consentement éclairé), et (b) de l'épinglage SHA-256 qui vérifie que les octets correspondent.

Si vous préférez le chemin de confiance natif de la plateforme, utilisez la voie npm install -g — npm fournit ses propres attestations de provenance pour @zenovay/cli.

Installations multiples

Si vous installez le CLI par plusieurs voies (npm + brew est le cas courant), zenovay doctor signale le conflit et indique la commande de nettoyage adaptée :

zenovay doctor
# ⚠  Conflit de chemin d'installation
# Plusieurs binaires zenovay détectés sur le PATH :
#   • /Users/you/.npm-global/bin/zenovay  [npm-global] (premier sur le PATH)
#   • /opt/homebrew/bin/zenovay  [brew]
# Choisissez-en un et désinstallez les autres pour éviter les écarts de version :
#   npm uninstall -g @zenovay/cli
#   brew uninstall zenovay

Connexion

Le CLI utilise OAuth 2.0 device flow — votre navigateur est la frontière de confiance, et aucun mot de passe à longue durée de vie ne touche jamais le CLI.

zenovay login

Le CLI affiche un court user_code et ouvre votre navigateur sur app.zenovay.com/cli/authorize. Approuvez la demande, choisissez l'équipe à laquelle le token doit être limité, et le CLI termine la connexion automatiquement.

Les tokens sont stockés dans ~/.config/zenovay/auth.json avec des permissions 0600. Les refresh tokens tournent à chaque utilisation.

Pour changer de compte, exécutez zenovay logout puis reconnectez-vous.

Travailler sur plusieurs équipes

Si votre compte appartient à plusieurs équipes, le CLI utilise par défaut celle que vous avez sélectionnée à la connexion. Vous pouvez la remplacer commande par commande :

zenovay events tail --team-id 6f3e…

Programmatiquement (lors d'appels directs à l'External API), passez l'id de l'équipe en en-tête :

X-Zenovay-Team-Id: 6f3e…

L'endpoint GET /v1/cli/me retourne la liste complète des équipes auxquelles la clé courante a accès.

Commandes courantes

Exécutez zenovay <command> --help pour toutes les options.

Annotations de graphique

Marquez déploiements, releases, campagnes, incidents et événements custom sur chaque graphique temporel Zenovay depuis votre pipeline CI.

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

Options :

Limites de plan : Free = 10 annotations / mois par équipe. Pro et au-delà sont illimités.

Déduplication : une annotation du même type dans les 5 minutes suivant une existante est rejetée avec HTTP 409 (code de sortie CLI 5). Cela protège contre les pipelines CI mal configurés qui posteraient sinon le même marqueur de déploiement deux fois.

Exemple GitHub Actions

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

Les annotations alimentent aussi le triage des incidents de conversion : tout incident ouvert dans une fenêtre de ±2 heures autour d'une annotation l'inscrit comme « changement suspect » dans le panneau de détail.

Utilisation programmatique (External API)

Les mêmes tokens CLI fonctionnent pour les appels directs à l'External API. Voir l'article d'aide Webhooks pour la livraison d'événements sortants et l'article Export du journal d'audit pour l'archivage de conformité.

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

Chaque réponse de l'API contient un en-tête x-request-id — incluez-le dans vos tickets de support pour que nous puissions tracer l'appel exact.

Récapitulatif des plans et des limites de débit

Les fonctionnalités IA du CLI (zenovay ai, l'assistant d'installation IA) sont limitées par le quota de commandes IA. Les commandes CLI simples (sites, events tail, watch) ne comptent que dans la limite de débit de l'API.

Source et suivi des problèmes

Le code source du CLI est privé pour l'équipe Zenovay, mais les binaires publiés et le paquet npm sont publics. Les demandes de fonctionnalités et les rapports de bug sont les bienvenus sur community.zenovay.com.