Zenovay CLI

Zenovay CLI（@zenovay/cli）は、シェルからZenovay Analyticsをインストール、設定、探索するためのターミナルアプリです。AIインストールウィザードとTUIダッシュボードを組み合わせており、アナリティクスの導入、ライブイベントの確認、デバッグを同じ場所から行えます。

CLIは公開された、お客様向けのツールです。請求やチームの設定などのアカウント管理は、引き続きapp.zenovay.comのダッシュボードで行います。

インストール

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はプライベートです
brew tap zenovay/zenovay
brew install zenovay/zenovay/zenovay

Homebrewのtapはzenovay/homebrew-zenovay（GitHubのプライベートリポジトリ）にあります。BrewはtapのクローンとリリースアセットのダウンロードのためにHOMEBREW_GITHUB_API_TOKENを必要とします。GitHub CLIをすでにインストールしている場合は、gh auth tokenを使うのが最も簡単です。永続化するには、上記のexport行を~/.zshrcまたは~/.bashrcに追加してください。

npm（Node ≥ 20のすべてのプラットフォーム）

npm install -g @zenovay/cli

インストール後、次のコマンドで確認します。

zenovay --version

信頼モデル

バイナリはZenovayのリリース鍵ペアによってEd25519署名されています。インストールスクリプトとHomebrew formulaは、SHA-256がマニフェストと一致しない場合はインストールを拒否します。改ざんされたバイナリは常に拒否されます。

ZenovayはApple Developer Programに参加していないため、バイナリはAppleのノータライズを受けていません。インストールスクリプトとHomebrew formulaは、macOSのGatekeeperの隔離属性（xattr -d com.apple.quarantine）を取り除き、「開けません」というプロンプトなしでバイナリを実行できるようにします。これはbun、deno、uvと同じ姿勢です。信頼の根拠は、（a）お客様自身が明示的にcurl … | shまたはbrew installを実行すること（インフォームドコンセント）、および（b）SHA-256ピンによってバイトが一致することの検証です。

プラットフォームネイティブの信頼経路をご希望の場合は、npm install -gの経路をご利用ください。npmは@zenovay/cliに対して独自のプロベナンス証明（provenance attestation）を提供しています。

複数のインストール

CLIを複数の経路でインストールしている場合（npm + brewが一般的なケース）、zenovay doctorが競合を検出し、適切なクリーンアップコマンドを案内します。

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

ログイン

CLIはOAuth 2.0デバイスフローを使用します。信頼境界はブラウザにあり、長期間有効なパスワードがCLIに渡ることはありません。

zenovay login

CLIは短いuser_codeを表示し、ブラウザでapp.zenovay.com/cli/authorizeを開きます。そこでリクエストを承認し、トークンのスコープとなるチームを選択すると、CLIはログインを自動的に完了します。

トークンは~/.config/zenovay/auth.jsonにパーミッション0600で保存されます。リフレッシュトークンは使用のたびにローテーションされます。

アカウントを切り替えるには、zenovay logoutを実行してから再度ログインしてください。

複数チームでの利用

アカウントが複数のチームに属している場合、CLIはログイン時に選択したチームをデフォルトとして使用します。コマンドごとに上書きすることもできます。

zenovay events tail --team-id 6f3e…

プログラムから（External APIを直接呼び出す場合）は、チームidをヘッダーで渡します。

X-Zenovay-Team-Id: 6f3e…

エンドポイントGET /v1/cli/meは、現在のキーがアクセスできるチームの完全な一覧を返します。

よく使うコマンド

すべてのオプションを確認するにはzenovay <command> --helpを実行してください。

チャートアノテーション

CIパイプラインから、すべてのZenovay時系列チャートにデプロイ／リリース／ キャンペーン／インシデント／カスタムイベントのマーカーを付けられます。

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

フラグ:

プラン上限: Free = チームあたり月10アノテーション。Pro以上は無制限。

重複防止: 既存のアノテーションから5分以内の同じtypeはHTTP 409（CLI終了 コード5）で拒否されます。誤設定されたCIパイプラインが同じデプロイマーカーを 二重に投稿することを防ぎます。

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

アノテーションはコンバージョンインシデント分析にも利用されます。 インシデント発生時刻の±2時間以内のアノテーションは、インシデント詳細パネルに 「疑わしい変更」として一覧表示されます。

プログラムからの利用（External API）

同じCLIトークンはExternal APIへの直接呼び出しにも使用できます。アウトバウンドのイベント配信についてはWebhookのヘルプ記事を、コンプライアンス用アーカイブについては監査ログのエクスポート記事を参照してください。

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

すべてのAPIレスポンスにはx-request-idヘッダーが含まれます。サポートチケットに含めていただくと、該当の呼び出しを正確に追跡できます。

プランとレート制限のまとめ

CLIのAI機能（zenovay ai、AIインストールウィザード）はAIコマンドの上限の対象です。通常のCLIコマンド（sites、events tail、watch）はAPIのレート制限のみの対象となります。

ソースとイシュートラッキング

CLIのソースはZenovayチーム内で非公開ですが、公開されているバイナリとnpmパッケージは公開です。機能リクエストやバグ報告はcommunity.zenovay.comまでお寄せください。