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-Tracking bereitstellen, 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. Um dies dauerhaft zu machen, 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 Binaries nicht Apple-notarisiert; die Installationsskripte und die Homebrew-Formula entfernen das macOS-Gatekeeper-Quarantäne-Attribut (xattr -d com.apple.quarantine), damit das Binary ohne „cannot be opened"-Hinweis ausgeführt wird. Dasselbe Vorgehen wie bei bun, deno und uv. Vertrauen kommt durch (a) Ihre explizite Ausführung von curl … | sh oder brew install (informierte Zustimmung) und (b) den SHA-256-Pin, der verifiziert, dass die Bytes übereinstimmen.

Wenn Sie den plattform-nativen Vertrauenspfad bevorzugen, verwenden Sie die npm install -g-Route — npm bietet seine eigenen Provenance Attestations für @zenovay/cli.

Mehrfache Installationen

Wenn Sie die CLI über mehrere Wege installiert haben (npm + brew ist der häufigste Fall), meldet zenovay doctor den Konflikt und zeigt auf den richtigen 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 es gelangt niemals ein langlebiges Passwort 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 Konten zu wechseln, führen Sie zenovay logout aus und melden Sie sich erneut an.

Arbeiten mit mehreren Teams

Wenn Ihr Konto zu mehr als einem Team gehört, verwendet das CLI standardmäßig das Team, das Sie bei der Anmeldung ausgewählt haben. 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 gibt die vollständige Liste der Teams zurück, auf die der aktuelle Key Zugriff hat.

Häufige Befehle

Führen Sie zenovay <command> --help aus, um alle Optionen anzuzeigen.

Chart-Anmerkungen

Markieren Sie Deploys, Releases, Kampagnen, Vorfälle und benutzerdefinierte 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 und höher = unbegrenzt.

Dedup: Eine Anmerkung desselben Typs innerhalb von 5 Minuten zu einer bestehenden wird mit HTTP 409 (CLI-Exitcode 5) abgelehnt. Dies schützt vor fehlkonfigurierten CI-Pipelines, die andernfalls denselben Deploy-Marker zweimal 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 }}

Anmerkungen fließen auch in die Conversion-Incident-Triage ein: Jeder Vorfall, der innerhalb von ±2 Stunden zu einer Anmerkung geöffnet wird, listet diese im Incident-Detailfeld als „verdächtige Änderung".

Programmatische Nutzung (External API)

Die gleichen CLI-Tokens funktionieren auch für direkte External-API-Aufrufe. 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

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

Quellcode und Issue-Tracking

Der CLI-Quellcode 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.