Zenovay CLI

The Zenovay CLI (@zenovay/cli) is a terminal app for installing, configuring, and exploring Zenovay analytics from your shell. It pairs an AI install wizard with a TUI dashboard so you can ship analytics, watch live events, and debug from the same place.

The CLI is a public, customer-facing tool. Account-management for billing and team settings still happens in the dashboard at app.zenovay.com.

Install

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 is private
brew tap zenovay/zenovay
brew install zenovay/zenovay/zenovay

The Homebrew tap is at zenovay/homebrew-zenovay (private GitHub repo). Brew needs HOMEBREW_GITHUB_API_TOKEN to clone the tap and download release assets — easiest path is gh auth token if you already have GitHub CLI installed. To make it permanent, add the export line to ~/.zshrc or ~/.bashrc.

npm (any platform with Node ≥ 20)

npm install -g @zenovay/cli

After install, verify with:

zenovay --version

Trust model

Binaries are Ed25519-signed by the Zenovay release keypair — the install scripts and Homebrew formula refuse to install if the SHA-256 doesn't match the manifest. Tampered binaries are rejected, always.

We do not participate in the Apple Developer Program, so binaries are not Apple-notarized; the install scripts and Homebrew formula strip the macOS Gatekeeper quarantine attribute (xattr -d com.apple.quarantine) so the binary runs without a "cannot be opened" prompt. Same posture as bun, deno, and uv. Trust comes from (a) you explicitly running curl … | sh or brew install (informed consent), and (b) the SHA-256 pin verifying the bytes match.

If you'd prefer the platform-native trust path, use the npm install -g route — npm provides its own provenance attestations for @zenovay/cli.

Multiple installations

If you install the CLI through more than one path (npm + brew is the common case), zenovay doctor flags the conflict and points you at the right cleanup command:

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

Log in

The CLI uses OAuth 2.0 device flow — your browser is the trust boundary, and no long-lived password ever touches the CLI.

zenovay login

The CLI prints a short user_code and opens your browser to app.zenovay.com/cli/authorize. Approve the request there, choose which team the token should be scoped to, and the CLI completes the login automatically.

Tokens are stored at ~/.config/zenovay/auth.json with 0600 permissions. Refresh tokens rotate on every use.

To switch accounts, run zenovay logout and log in again.

Working across multiple teams

If your account belongs to more than one team, the CLI defaults to the team you selected at login. You can override on a per-command basis:

zenovay events tail --team-id 6f3e…

Programmatically (when calling the External API directly), pass the team id as a header:

X-Zenovay-Team-Id: 6f3e…

The endpoint GET /v1/cli/me returns the full list of teams the current key has access to.

Common commands

Run zenovay <command> --help for full options.

Chart annotations

Mark deploys, releases, campaigns, incidents, and custom events on every Zenovay timeseries chart from your CI pipeline.

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

Flags:

Plan limits: Free = 10 annotations / month per team. Pro and above are unlimited.

Dedup: a same-type annotation within 5 minutes of an existing one is rejected with HTTP 409 (CLI exit code 5). This protects against misconfigured CI pipelines that would otherwise post the same deploy marker twice.

GitHub Actions example

- 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 also feed the conversion incident triage: any incident opened within ±2 hours of an annotation lists it as a "suspect change" in the incident detail panel.

Programmatic use (External API)

The same CLI tokens work for direct External API calls. See the Webhooks help article for outbound event delivery and the Audit Log Export article for compliance archival.

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

Every API response carries an x-request-id header — include it in support tickets so we can trace the exact call.

Plan and rate-limit summary

CLI AI features (zenovay ai, the AI install wizard) are gated by the AI command limit. Plain CLI commands (sites, events tail, watch) only count against the API rate limit.

Source and issue tracking

The CLI source is private to the Zenovay team, but the published binaries and the npm package are public. Feature requests and bug reports are welcome at community.zenovay.com.