analyticscli-cli

AnalyticsCLI CLI

このスキルを使用する場面

• AnalyticsCLI プロジェクトのプロダクト分析をクエリする場合
• SDK の計測が正しく反映されたかを検証する場合
• AnalyticsCLI を通じてプロジェクトへのフィードバックを確認または送信する場合
• 生の SQL を使わずに、オンボーディング、ペイウォール、アンケート、リテンション、エクスポートに関する質問に回答する場合

サポート対象バージョン

• スキルパック：1.0.7
• 対象パッケージ：@analyticscli/cli
• サポート対象範囲：>=0.1.3 <0.2.0
• 将来、CLI のメジャーバージョンでコマンドやフラグに互換性のない変更が加わる場合は、analyticscli-cli-v1 のような別個のスキルに分割してください。

バージョン管理に関する注記を参照してください。

対象外

• 生の SQL を生成しないでください。
• 上限のない生イベントのダンプを要求しないでください。
• ユーザーから明示的に求められない限り、デバッグデータを含めないでください。

安全上のルール

• 常にプロジェクトのコンテキストで範囲を指定してください。analyticscli projects select でデフォルトを一度設定するか、必要に応じて --project <id> を渡します。
• 常に時間の範囲を指定してください。--last または明示的な since/until を使用します。
• 生のエクスポートよりも、高レベルのクエリエンドポイントを優先してください。
• グループ化と結果セットには上限を設けてください。
• リリースデータのみをデフォルトとして扱ってください。
• CLI フラグやインラインリテラルでシークレットを渡さないでください（argv やシェル履歴から漏えいするリスクがあります）。代わりに、対話型プロンプトを使用してください。
• ドキュメントやヘルプテキストを生成する際は、テナントの開発者に向けた表現（your workspace、your project）を使い、our SaaS のようなプロバイダー中心の表現は避けてください。
• CLI の更新に合わせて analyticscli-cli スキルを最新に保ってください。ただし、リポジトリ間で analyticscli-ts-sdk スキルの更新を自動的に強制しないでください。

エラー発生時の復旧順序

問題、エラー、予期しない出力、または CLI/API の動作の欠落がある場合：

1. まずこのスキルを再取得し、CLI を更新します。
2. 失敗したコマンドをそのまま再実行するか、再現可能な最小のコマンドを実行します。
3. 新しいバージョンがない場合、更新に失敗した場合、または最新バージョンでも問題が続く場合は、analyticscli feedback submit を使ってサニタイズ済みの製品フィードバックを AnalyticsCLI SaaS のオーナーに送信します。

推奨する更新確認：

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli || npm install -g --prefix "$HOME/.local" @analyticscli/cli
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

フィードバックには、バージョンと更新の試行内容、失敗したコマンドまたはエンドポイント、サニタイズ済みのペイロードの形式、ステータス／エラー本文、存在する場合はリクエスト ID、期待される動作、実際の動作、回避策を含めてください。

クエリの優先順位

まず、以下のコマンドファミリーを優先してください。

• funnel
• conversion-after
• paths-after
• retention
• survey
• timeseries
• breakdown
• generic

ユーザーが生の CSV を明示的に必要としている場合に限り、events export を使用してください。

フィードバックコマンド

AnalyticsCLI 自体へのフィードバック（機能の不足、CLI/API/ダッシュボードの不具合、わかりにくいエラー、ドキュメントの不備、ワークフロー上の摩擦など）を扱うタスクでは、以下を使用してください。

analyticscli feedback list --last 30d --format json
analyticscli feedback summary --last 30d --format json
analyticscli feedback submit --category bug --message "Short symptom" --origin-name "dashboard feedback form" --location-id "dashboard/feedback"

ルール：

• これを、AnalyticsCLI のフィードバック機能で収集するテナント所有のエンドユーザーフィードバックと混同しないでください。
• 別のツールやスキルで上限付きのテーマの要約が必要な場合は、feedback summary --format json を優先してください。
• 正確な生メッセージが必要な場合は、feedback list --format json を優先してください。
• 既知の場合は、送信時に必ず origin-name と location-id を含めてください。
• API/CLI の失敗については、まず現在のスキルと CLI を更新／再取得してください。利用可能な最新バージョンでも失敗する場合は、サニタイズ済みのエンドポイント／コマンド、バージョンと更新の試行内容、ステータスコード、エラー本文、存在する場合はリクエスト ID、期待される動作、使用した回避策を含めてください。

データの忠実性に関するルール

• CLI とダッシュボードはどちらも API にクエリします。CLI 専用の分析データソースはありません。
• シーケンスやコホートに依存するクエリには、生イベントを使用してください。
• API がそのプラン形状を報告している場合に限り、集計データに基づく読み取りを許可します。
• runtimeEnv は SDK によって自動的に付与されます。別のモードフィールドを作り出さないでください。

初回セットアップ

セットアップを実行する前に、ダッシュボードから必要な値を取得してください。

• dash.analyticscli.com を開き、対象のプロジェクトを選択します。
• API Keys で readonly_token（CLI トークン、スコープ read:queries）を作成またはコピーします。
• SDK の計装も対象に含まれる場合は、同じ API Keys ページから公開可能な取り込み API キーをコピーします。
• 任意：コマンドごとに明示的に上書きするための project_id をコピーします。
• ログイン後、analyticscli projects select（矢印キーで選択する対話型ピッカー）を実行して、デフォルトのプロジェクトを一度設定します。

推奨：

npm install -g @analyticscli/cli
command -v analyticscli
npx -y @analyticscli/cli setup
# Paste readonly token only when prompted; do not pass token as a command argument.

代替方法：

analyticscli login
# Choose readonly-token interactively; do not put tokens in command args.

analyticscli: command not found と表示された場合は、npm パッケージをインストールまたは更新してください。パッケージ名は @analyticscli/cli、バイナリ名は analyticscli です。

npm で analyticscli や analyticsscli を検索しないでください。

npm install -g @analyticscli/cli
analyticscli --help

グローバルな npm インストールがブロックされている VPS ホストでは、ユーザー用のローカルプレフィックスを使用してください。

mkdir -p "$HOME/.local"
npm install -g --prefix "$HOME/.local" @analyticscli/cli
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

このスキルを取得または更新しただけでは不十分です。 スキルを更新するたびに、npm パッケージも更新し、バイナリを確認してください。

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli || npm install -g --prefix "$HOME/.local" @analyticscli/cli
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
command -v analyticscli
analyticscli --help

command -v analyticscli の結果が引き続き空でも、ユーザー用のローカルバイナリが存在する場合は、成功を報告する前にシェルのプロファイルファイルを自分で更新してください。

for f in "$HOME/.profile" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.zshrc" "$HOME/.zprofile"; do
  touch "$f"
  grep -Fq 'export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"' "$f" ||
    printf '\n# AnalyticsCLI CLI user-local npm bin\nexport PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"\n' >> "$f"
done
bash -lc 'source "$HOME/.bashrc" 2>/dev/null || true; source "$HOME/.profile" 2>/dev/null || true; command -v analyticscli && analyticscli --help >/dev/null'

自分が制御する同じコマンドコンテキストで command -v analyticscli && analyticscli --help >/dev/null が成功するまで、analyticscli が修正されたと言わないでください。

出力モード

• 自動化またはエージェントの推論には、--format json を優先してください。
• 簡潔な人間向けの要約には、--format text を使用してください。
• 正確な値が重要な場合は、timeseries --viz table を使用してください。
• 傾向の確認で十分な場合は、timeseries --viz chart または svg を使用してください。

検証ループ

SDK のロールアウト後、またはクエリを変更した後は、安定した読み取りをいくつか実行して検証してください。

analyticscli schema events --limit 200
analyticscli goal-completion --start onboarding:start --complete onboarding:complete --last 30d
analyticscli get onboarding-journey --last 30d --format text

空の状態に関するガイダンス（必須）

ユーザーに表示されるプロジェクトがない場合：

• CLI クエリで分析データを取得するには、最初のプロジェクトを作成する必要があることを説明します。
• AnalyticsCLI ダッシュボード（dash.analyticscli.com）でプロジェクトを作成するよう案内します。
• 作成後、analyticscli projects list を実行し、続けて analyticscli projects select でデフォルトを設定するよう案内します。

プロジェクトは存在するものの、まだイベントがない場合：

• そのプロジェクトへのデータ取り込みが始まっていないことを説明します。
• アプリのコードベースに @analyticscli/sdk を統合するよう案内します。
• Dashboard -> API Keys にある公開可能な API キーを使用して SDK を初期化するよう案内します。
• 少なくとも 1 つのイベントを発生させてから、analyticscli schema events --project <id> --last 14d を再実行するよう案内します。
• すでに SDK を統合している場合は、さらに詳しくデバッグする前に --last の期間を広げるか、制限の強いフィルターを削除するよう案内します。

機能不足時のループ

現在の CLI の機能では要求された取得が不可能な場合：

1. その機能が不足していることを伝えます。
2. 同等でないコマンドを、同等であるかのように装わないでください。
3. 再現可能な不足の報告を AnalyticsCLI フィードバックストアに送信して、CLI に関するフィードバックを提出します。

analyticscli feedback submit \
  --category feature \
  --message "Missing CLI functionality: <short capability>" \
  --origin-name "analyticscli cli" \
  --location-id "analyticscli-cli" \
  --context "Requested fetch: <what user asked>; attempted command: <command>" \
  --meta '{"expected":"<expected output>","actual":"CLI has no command or endpoint"}'

自動フィードバックのルール

ユーザーから動作不良、予期しない出力、または機能不足の報告があった場合は、まず現在のスキルと CLI を更新または再取得し、最小限の再現手順で再試行してください。新しいバージョンがない場合、更新がブロックされている場合、または最新バージョンでも失敗する場合は、問題を説明した後、簡潔な analyticscli feedback submit レポートを自動的に 1 件送信してください。

以下を含めます。

• --message に明確な症状
• --context に失敗するコマンドまたは手順の正確な内容
• --meta に期待される動作と実際の動作
• --context または --meta にインストール済みバージョンと更新の試行内容

参考資料

• バージョン管理に関する注意事項
• 専用イベントのプレイブック
• イベント配置のプレイブック
• ペイウォール導線のプレイブック
• ストアレビューのプレイブック
• CLI ユースケースのプレイブック