SKILL.md

$28

# 1. Flag (highest priority -- overrides everything)

dune query run 12345 --api-key <key>

# 2. Environment variable

export DUNE_API_KEY=<key>

dune query run 12345

# 3. Saved config file (lowest priority)

dune auth --api-key <key>        # saves to ~/.config/dune/config.yaml

dune query run 12345              # uses saved key

To save your key interactively (prompted from stdin):

dune auth

Config file location: ~/.config/dune/config.yaml

Global Flags

Flag

Description

--api-key <KEY>

Dune API key (overrides DUNE_API_KEY env var and saved config)

Output Format (per-command flag)

Most commands support -o, --output <FORMAT> with values text (default, human-readable tables) or json (machine-readable).

**Always use -o json** on every command that supports it. JSON output contains more detail than text (full API response objects vs. summarized tables) and is unambiguous to parse. The text format is for human terminal use and drops fields.

DuneSQL

Dune uses DuneSQL, a Trino-based SQL dialect, as its query engine. Key points:

All SQL passed to --sql flags or saved queries must be valid DuneSQL

DuneSQL supports standard SQL with extensions for blockchain data types (addresses, hashes, etc.)

See dunesql-cheatsheet.md for common types, functions, patterns, and pitfalls

Use dune docs search --query "DuneSQL functions" to look up syntax and functions

Reference docs: Writing Efficient Queries, Functions and Operators

Key Concepts

Performance Tiers

Available tiers: small, medium, large. **Do not pass --performance by default** — omit it and the API auto-selects. Only provide it when:

The user explicitly requests a tier

The query is clearly complex (heavy joins, large aggregations)

A previous run returned a timeout or resource-limit error

Execution States

After submitting a query, the execution progresses through these states:

State

Meaning

Action

QUERY_STATE_PENDING

Queued for execution

Wait

QUERY_STATE_EXECUTING

Currently running

Wait

QUERY_STATE_COMPLETED

Results available

Fetch results

QUERY_STATE_FAILED

Execution failed

Check error message; fix SQL and retry

QUERY_STATE_CANCELLED

Cancelled by user or system

Re-execute if needed

Dataset Categories

Dataset Types

Type

Description

dune_table

Core Dune-maintained tables

decoded_table

Contract ABI-decoded tables

spell

Spellbook transformation tables

uploaded_table

User-uploaded CSV/data tables

transformation_table

Materialized transformation tables

transformation_view

Virtual transformation views

Query Parameters

Parameters let you create reusable queries with variable inputs. Pass them as --param key=value (repeatable). The API auto-detects the type, but parameters support these types: text, number, datetime, enum.

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

Command Overview

Command

Description

Auth

dune auth

Save API key to config file

dune query create

Create a new saved query

Yes

dune query get <id>

Fetch a saved query's SQL and metadata

Yes

dune query update <id>

Update an existing query

Yes

dune query archive <id>

Archive a saved query

Yes

dune query run <id>

Execute a saved query and wait for results

Yes

dune query run-sql

Execute raw DuneSQL directly (no saved query needed)

Yes

dune execution results <id>

Fetch results of a previous execution

Yes

dune dataset search

Search the Dune dataset catalog

Yes

dune dataset search-by-contract

Find decoded tables for a contract address

Yes

dune viz create

Create a visualization on a saved query

Yes

dune viz get <id>

Fetch visualization details and options

Yes

dune viz list

List all visualizations for a query

Yes

dune viz update <id>

Update an existing visualization

Yes

dune viz delete <id>

Permanently delete a visualization

Yes

dune docs search

Search Dune documentation

dune usage

Show credit and resource usage

Yes

dune dashboard create

Create a new dashboard

Yes

dune dashboard get <id>

Fetch a dashboard's metadata and widgets

Yes

dune dashboard update <id>

Update an existing dashboard

Yes

dune dashboard archive <id>

Archive a dashboard

Yes

Common Workflows

Ad-hoc SQL Analysis

# Run a one-off query directly

dune query run-sql --sql "SELECT block_number, block_time FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5" -o json

Discover Tables, Then Query

# 1. Find relevant tables with column schemas

dune dataset search --query "uniswap swaps" --categories decoded --include-schema -o json

# 2. Write and execute SQL using discovered table/column names

dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Swap LIMIT 10" -o json

Find Contract Tables, Then Query

# 1. Find decoded tables for a specific contract

dune dataset search-by-contract --contract-address 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 --include-schema -o json

# 2. Query the discovered tables

dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Transfer LIMIT 10" -o json

Save and Execute a Reusable Query

# 1. Create a saved query with parameters

dune query create --name "Top Wallets" --sql "SELECT address, balance FROM ethereum.balances WHERE balance > {{min_balance}} LIMIT {{row_limit}}" -o json

# 2. Run it with parameter values

dune query run <returned-id> --param min_balance=1000 --param row_limit=50 -o json

Long-Running Query (Submit and Poll)

# 1. Submit without waiting

dune query run 12345 --no-wait --performance large -o json

# Output: {"execution_id": "01ABC...", "state": "QUERY_STATE_PENDING"}

# 2. Check results later

dune execution results 01ABC... -o json

Build a Dashboard from Scratch

# 1. Create queries for each section

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. Execute to verify data

dune query run $QUERY_ID -o json

# 3. Create visualizations for each query

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. Assemble the dashboard

dune dashboard create --name "Trading Dashboard" \

  --text-widgets '[{"text":"# Trading Dashboard\nDaily volume and metrics"}]' \

  --visualization-ids $VIZ_ID -o json

Update a Dashboard (Preserve Existing Widgets)

# 1. Fetch current state

dune dashboard get 12345 -o json > dashboard.json

# 2. Modify as needed (add a new visualization widget)

# 3. Pass the complete widget state back

dune dashboard update 12345 \

  --visualization-widgets '[{"visualization_id":111},{"visualization_id":222},{"visualization_id":333}]' \

  -o json

Limitations

The following capabilities are available via the Dune MCP server or web UI but not via the CLI:

Blockchain listing (list all indexed blockchains with table counts)

Table size analysis (storage size of specific tables)

Security

Never output API keys or tokens in responses. Before presenting CLI output to the user, scan for strings that look like API keys (e.g. long alphanumeric tokens, strings prefixed with dune_, or values from DUNE_API_KEY). Redact them with [REDACTED].

Always confirm with the user before running write commands (query create, query update, query archive, viz create, viz update, viz delete, dashboard create, dashboard update, dashboard archive)

Always use -o json on every command -- JSON output is more detailed and reliably parseable

Use --temp when creating throwaway queries to avoid cluttering the user's saved queries

Never pass --api-key on the command line when other users might see the terminal history. Prefer dune auth or the DUNE_API_KEY environment variable.