Zenovay CLI

Das Zenovay CLI (@zenovay/cli) ist eine Terminal-App zum Installieren, Konfigurieren und Erkunden von Zenovay Analytics aus Ihrer Shell. Es kombiniert einen KI-Installationsassistenten mit einem TUI-Dashboard, sodass Sie Analytics ausliefern, Live-Events beobachten und debuggen können — alles am selben Ort.

Das CLI ist ein öffentliches, kundenseitiges Tool. Account-Verwaltung für Abrechnung und Team-Einstellungen erfolgt weiterhin im Dashboard unter 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)   # Tap ist privat
brew tap zenovay/zenovay
brew install zenovay/zenovay/zenovay

Der Homebrew-Tap liegt unter zenovay/homebrew-zenovay (privates GitHub-Repository). Brew benötigt HOMEBREW_GITHUB_API_TOKEN, um den Tap zu klonen und Release-Assets herunterzuladen — am einfachsten über gh auth token, falls Sie die GitHub CLI bereits installiert haben. Damit dies dauerhaft funktioniert, fügen Sie die export-Zeile zu ~/.zshrc oder ~/.bashrc hinzu.

npm (jede Plattform mit Node ≥ 20)

npm install -g @zenovay/cli

Überprüfen Sie nach der Installation:

zenovay --version

Vertrauensmodell

Binaries werden mit dem Zenovay-Release-Schlüsselpaar Ed25519-signiert — die Installationsskripte und die Homebrew-Formula verweigern die Installation, wenn der SHA-256 nicht mit dem Manifest übereinstimmt. Manipulierte Binaries werden grundsätzlich abgelehnt.

Wir nehmen nicht am Apple Developer Program teil, daher sind die Binaries nicht Apple-notarisiert; die Installationsskripte und die Homebrew-Formula entfernen das Quarantäne-Attribut von macOS Gatekeeper (xattr -d com.apple.quarantine), damit das Binary ohne „kann nicht geöffnet werden"-Hinweis startet. Gleiche Vorgehensweise wie bei bun, deno und uv. Vertrauen entsteht durch (a) Ihre explizite Ausführung von curl … | sh oder brew install (informierte Zustimmung) und (b) den SHA-256-Pin, der die Bytes verifiziert.

Wenn Sie den plattform-nativen Vertrauenspfad bevorzugen, verwenden Sie den npm install -g-Weg — npm liefert eigene Provenance Attestations für @zenovay/cli.

Mehrfache Installationen

Wenn Sie das CLI über mehrere Wege installiert haben (npm + brew ist der häufigste Fall), meldet zenovay doctor den Konflikt und verweist auf den passenden Bereinigungsbefehl:

zenovay doctor
# ⚠  Install path conflict
# Multiple zenovay binaries detected on PATH:
#   • /Users/you/.npm-global/bin/zenovay  [npm-global] (first on PATH)
#   • /opt/homebrew/bin/zenovay  [brew]
# Pick one and uninstall the others to avoid version drift:
#   npm uninstall -g @zenovay/cli
#   brew uninstall zenovay

Anmeldung

Das CLI verwendet OAuth 2.0 Device Flow — Ihr Browser ist die Vertrauensgrenze, und kein langlebiges Passwort gelangt jemals ins CLI.

zenovay login

Das CLI gibt einen kurzen user_code aus und öffnet Ihren Browser unter app.zenovay.com/cli/authorize. Bestätigen Sie die Anfrage dort, wählen Sie das Team aus, auf das das Token beschränkt sein soll, und das CLI schließt die Anmeldung automatisch ab.

Tokens werden unter ~/.config/zenovay/auth.json mit 0600-Berechtigungen gespeichert. Refresh-Tokens werden bei jeder Verwendung rotiert.

Um das Konto zu wechseln, führen Sie zenovay logout aus und melden sich erneut an.

Arbeiten mit mehreren Teams

Wenn Ihr Konto zu mehr als einem Team gehört, verwendet das CLI standardmäßig das beim Login ausgewählte Team. Sie können dies pro Befehl überschreiben:

zenovay events tail --team-id 6f3e…

Programmatisch (bei direkten Aufrufen der External API) übergeben Sie die Team-id als Header:

X-Zenovay-Team-Id: 6f3e…

Der Endpunkt GET /v1/cli/me liefert die vollständige Liste der Teams, auf die der aktuelle Key Zugriff hat.

Häufige Befehle

Führen Sie zenovay <command> --help für alle Optionen aus.

Chart-Annotations

Markieren Sie Deploys, Releases, Kampagnen, Vorfälle und custom-Events auf jedem Zenovay-Zeitreihen-Chart direkt aus Ihrer CI-Pipeline.

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

Flags:

Plan-Limits: Free = 10 Annotations / Monat pro Team. Pro+ = unbegrenzt.

Dedup: Eine gleichartige Annotation innerhalb von 5 Minuten zu einer bestehenden wird mit HTTP 409 (CLI-Exitcode 5) abgelehnt. Schützt vor fehlkonfigurierten CI-Pipelines, die denselben Deploy-Marker doppelt posten würden.

GitHub-Actions-Beispiel

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

Annotations fließen außerdem in das Conversion-Incident-Triage ein: Jeder Vorfall, der innerhalb von ±2 Stunden um eine Annotation geöffnet wird, listet sie im Detailfeld als „verdächtige Änderung".

Programmatische Nutzung (External API)

Dieselben CLI-Tokens funktionieren auch für direkte Aufrufe der External API. Siehe den Webhooks-Hilfeartikel für ausgehende Event-Zustellung und den Audit-Log-Export-Artikel für Compliance-Archivierung.

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

Jede API-Antwort enthält einen x-request-id-Header — geben Sie ihn in Support-Tickets an, damit wir den exakten Aufruf nachverfolgen können.

Plan- und Rate-Limit-Übersicht

KI-Funktionen des CLI (zenovay ai, der KI-Installationsassistent) sind durch das KI-Befehlslimit begrenzt. Einfache CLI-Befehle (sites, events tail, watch) zählen nur gegen das API-Rate-Limit.

Quellcode und Issue-Tracking

Der Quellcode des CLI ist privat für das Zenovay-Team, aber die veröffentlichten Binaries und das npm-Paket sind öffentlich. Feature Requests und Bug Reports sind unter community.zenovay.com willkommen.