前提条件

Dune CLI はすでにインストールおよび認証済みであると想定します。実行前にインストールまたは認証チェックを実行しないでください。リクエストされた dune コマンドを直接実行してください。

dune コマンドが失敗した場合、エラーを検査してから install-and-recovery.md の回復手順に従ってください:

• 「command not found」 → CLI がインストールされていません。CLI Not Found Recovery を参照してください。
• 401 / 「unauthorized」/ 「missing API key」 → 認証失敗。Authentication Failure Recovery を参照してください。
• 不明なサブコマンドまたはフラグ / 予期しない出力 → バージョン不一致の可能性があります。Version Compatibility を参照してください。

Dune CLI

Dune 用のコマンドラインインターフェース -- ブロックチェーンデータプラットフォームの最大手。DuneSQL クエリをオンチェーンデータに対して記述および実行し、データセットを発見し、ドキュメントを検索し、クレジット使用状況を監視するために使用します。

認証

docs search 以外のすべてのコマンドは Dune API キーを介した認証が必要です。キーは次の優先度で解決されます:

# 1. フラグ (最優先 -- すべてをオーバーライド)
dune query run 12345 --api-key <key>

# 2. 環境変数
export DUNE_API_KEY=<key>
dune query run 12345

# 3. 保存された設定ファイル (最低優先度)
dune auth --api-key <key>        # ~/.config/dune/config.yaml に保存
dune query run 12345              # 保存されたキーを使用

キーをインタラクティブに保存する場合 (stdin からプロンプト):

dune auth

設定ファイルの場所: ~/.config/dune/config.yaml

グローバルフラグ

フラグ	説明
--api-key <KEY>	Dune API キー (DUNE_API_KEY 環境変数と保存された設定をオーバーライド)

出力形式 (コマンド別フラグ)

ほとんどのコマンドは -o, --output <FORMAT> をサポートしており、値は text (デフォルト、人間が読める形式のテーブル) または json (機械が読める形式) です。

すべてのコマンドで -o json を常に使用してください。JSON 出力は text よりも詳細情報を含み (完全な API レスポンスオブジェクト vs. サマリーテーブル)、解析が曖昧ではありません。text 形式は人間のターミナル用であり、フィールドを削除します。

DuneSQL

Dune は DuneSQL (Trino ベースの SQL 方言) をクエリエンジンとして使用します。主なポイント:

• --sql フラグまたは保存されたクエリに渡されるすべての SQL は有効な DuneSQL である必要があります
• DuneSQL は標準 SQL をサポートし、ブロックチェーンデータ型 (アドレス、ハッシュなど) の拡張機能があります
• 一般的な型、関数、パターン、落とし穴については dunesql-cheatsheet.md を参照してください
• dune docs search --query "DuneSQL functions" を使用して構文と関数を検索します
• リファレンスドキュメント: Writing Efficient Queries、Functions and Operators

主な概念

パフォーマンスティア

利用可能なティア: small、medium、large。デフォルトでは --performance を渡さないでください -- 省略すると API が自動的に選択します。次の場合にのみ指定してください:

• ユーザーが明示的にティアをリクエストした場合
• クエリが明らかに複雑な場合 (大量の結合、大規模な集計)
• 前回の実行がタイムアウトまたはリソース制限エラーを返した場合

実行状態

クエリを送信した後、実行は以下の状態を経由します:

状態	意味	アクション
QUERY_STATE_PENDING	実行待ち	待機
QUERY_STATE_EXECUTING	実行中	待機
QUERY_STATE_COMPLETED	結果利用可能	結果を取得
QUERY_STATE_FAILED	実行失敗	エラーメッセージを確認。SQL を修正して再試行
QUERY_STATE_CANCELLED	ユーザーまたはシステムによってキャンセル	必要に応じて再実行

データセットカテゴリ

カテゴリ	説明
canonical	コアブロックチェーンデータ (ブロック、トランザクション、トレース、ログ)
decoded	ABI デコードされたコントラクトデータ (イベントと関数呼び出し)
spell	Dune Spellbook 変換 (キュレーション済み、高レベルのテーブル (dex.trades など))
community	コミュニティ貢献のデータセット

データセットタイプ

タイプ	説明
dune_table	Dune が保守するコアテーブル
decoded_table	コントラクト ABI デコードテーブル
spell	Spellbook 変換テーブル
uploaded_table	ユーザーアップロードの CSV/データテーブル
transformation_table	具体化された変換テーブル
transformation_view	仮想変換ビュー

クエリパラメータ

パラメータを使用すると、変数入力を持つ再利用可能なクエリを作成できます。--param key=value として渡します (繰り返し可能)。API は型を自動検出しますが、パラメータはこれらの型をサポートします: text、number、datetime、enum。

dune query run 12345 --param wallet=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --param days=30 -o json

コマンド概要

コマンド	説明	認証
dune auth	API キーを設定ファイルに保存	いいえ
dune query create	新しい保存されたクエリを作成	はい
dune query get <id>	保存されたクエリの SQL とメタデータを取得	はい
dune query update <id>	既存のクエリを更新	はい
dune query archive <id>	保存されたクエリをアーカイブ	はい
dune query run <id>	保存されたクエリを実行して結果を待機	はい
dune query run-sql	生の DuneSQL を直接実行 (保存されたクエリ不要)	はい
dune execution results <id>	前回の実行の結果を取得	はい
dune dataset search	Dune データセットカタログを検索	はい
dune dataset search-by-contract	コントラクトアドレスのデコードテーブルを検索	はい
dune viz create	保存されたクエリの可視化を作成	はい
dune viz get <id>	可視化の詳細とオプションを取得	はい
dune viz list	クエリのすべての可視化をリスト	はい
dune viz update <id>	既存の可視化を更新	はい
dune viz delete <id>	可視化を永続的に削除	はい
dune docs search	Dune ドキュメントを検索	いいえ
dune usage	クレジットおよびリソース使用状況を表示	はい
dune dashboard create	新しいダッシュボードを作成	はい
dune dashboard get <id>	ダッシュボードのメタデータとウィジェットを取得	はい
dune dashboard update <id>	既存のダッシュボードを更新	はい
dune dashboard archive <id>	ダッシュボードをアーカイブ	はい

一般的なワークフロー

アドホック SQL 分析

# 1 回限りのクエリを直接実行
dune query run-sql --sql "SELECT block_number, block_time FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5" -o json

テーブルを発見してからクエリを実行

# 1. 列スキーマを含む関連テーブルを検索
dune dataset search --query "uniswap swaps" --categories decoded --include-schema -o json

# 2. 検出されたテーブル/列名を使用して SQL を記述および実行
dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Swap LIMIT 10" -o json

コントラクトテーブルを検索してからクエリを実行

# 1. 特定のコントラクトのデコードテーブルを検索
dune dataset search-by-contract --contract-address 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 --include-schema -o json

# 2. 検出されたテーブルをクエリ
dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Transfer LIMIT 10" -o json

再利用可能なクエリを保存して実行

# 1. パラメータを含む保存されたクエリを作成
dune query create --name "Top Wallets" --sql "SELECT address, balance FROM ethereum.balances WHERE balance > {{min_balance}} LIMIT {{row_limit}}" -o json

# 2. パラメータ値を指定して実行
dune query run <returned-id> --param min_balance=1000 --param row_limit=50 -o json

長時間実行クエリ (送信してポーリング)

# 1. 待機せずに送信
dune query run 12345 --no-wait --performance large -o json
# 出力: {"execution_id": "01ABC...", "state": "QUERY_STATE_PENDING"}

# 2. 後で結果を確認
dune execution results 01ABC... -o json

スクラッチからダッシュボードを構築

# 1. 各セクションのクエリを作成
QUERY_ID=$(dune query create --name "Daily Volume" --sql "SELECT date_trunc('day', block_time) AS day, SUM(amount) AS volume FROM trades GROUP BY 1 ORDER BY 1" -o json | jq -r '.query_id')

# 2. データを検証するために実行
dune query run $QUERY_ID -o json

# 3. 各クエリの可視化を作成
VIZ_ID=$(dune viz create --query-id $QUERY_ID --name "Daily Volume Chart" --type chart --options '{"globalSeriesType":"line","columnMapping":{"day":"x","volume":"y"}}' -o json | jq -r '.id')

# 4. ダッシュボードをアセンブル
dune dashboard create --name "Trading Dashboard" \
  --text-widgets '[{"text":"# Trading Dashboard\nDaily volume and metrics"}]' \
  --visualization-ids $VIZ_ID -o json

ダッシュボードを更新 (既存のウィジェットを保持)

# 1. 現在の状態を取得
dune dashboard get 12345 -o json > dashboard.json

# 2. 必要に応じて変更 (新しい可視化ウィジェットを追加)
# 3. 完全なウィジェット状態を返す
dune dashboard update 12345 \
  --visualization-widgets '[{"visualization_id":111},{"visualization_id":222},{"visualization_id":333}]' \
  -o json

制限事項

以下の機能は Dune MCP サーバーまたは Web UI では利用可能ですが、CLI では利用不可です:

• ブロックチェーンリスト (インデックス化されたすべてのブロックチェーンをテーブル数と共にリスト)
• テーブルサイズ分析 (特定のテーブルのストレージサイズ)

セキュリティ

• 決して API キーまたはトークンをレスポンスで出力しないでください。CLI 出力をユーザーに提示する前に、API キーに見える文字列 (例: 長い英数字トークン、dune_ で始まる文字列、または DUNE_API_KEY からの値) をスキャンします。[REDACTED] でマスクしてください。
• 常に 書き込みコマンド (query create、query update、query archive、viz create、viz update、viz delete、dashboard create、dashboard update、dashboard archive) を実行する前にユーザーに確認してください
• 常に すべてのコマンドで -o json を使用してください -- JSON 出力はより詳細で確実に解析可能です
• 使い捨てクエリを作成するときは --temp を使用してユーザーの保存されたクエリをクラッタにしないでください
• 決して 他のユーザーがターミナル履歴を見る可能性があるときにコマンドラインで --api-key を渡さないでください。dune auth または DUNE_API_KEY 環境変数を使用してください。

リファレンスドキュメント

詳細なコマンド構文とフラグが必要な場合に関連するリファレンスを読み込んでください:

タスク	リファレンス
保存されたクエリを作成、取得、更新、またはアーカイブ	query-management.md
クエリを実行 (run、run-sql) または実行結果を取得	query-execution.md
データセットを検索またはコントラクトアドレスのテーブルを検索	dataset-discovery.md
ドキュメントを検索またはアカウント使用状況を確認	docs-and-usage.md
DuneSQL 型、関数、一般的なパターン、落とし穴	dunesql-cheatsheet.md
保存されたクエリの可視化を作成、取得、更新、削除、またはリスト	visualization-management.md
ダッシュボードを作成、取得、更新、またはアーカイブ	dashboard-management.md
CLI インストール、認証、バージョン回復	install-and-recovery.md