Add search by contract functionality

Author: ivpusic

cli/root.go

@@ -24,12 +24,9 @@ var apiKeyFlag string
 
 var rootCmd = &cobra.Command{
 	Use:   "dune",
-	Short: "Dune CLI — query, explore, and manage blockchain data on Dune Analytics",
-	Long: "A command-line interface for the Dune Analytics platform.\n\n" +
-		"Discover datasets across the Dune catalog, execute SQL queries (DuneSQL dialect),\n" +
-		"retrieve execution results, and manage your saved queries — all from the terminal.\n\n" +
-		"Authenticate with an API key via --api-key, the DUNE_API_KEY environment variable,\n" +
-		"or by running `dune auth`.",
+	Short: "Dune CLI — interact with the Dune Analytics API",
+	Long: "A command-line interface for interacting with the Dune Analytics API.\n" +
+		"Manage queries, execute DuneSQL queries, search datasets, browse documentation, and monitor usage.",
 	PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
 		if cmd.Annotations["skipAuth"] == "true" {
 			return nil

cmd/dataset/dataset.go

@@ -6,8 +6,12 @@ import "github.com/spf13/cobra"
 func NewDatasetCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "dataset",
-		Short: "Discover and explore datasets across the Dune catalog",
+		Short: "Search and discover Dune datasets",
+		Long: "Search the Dune dataset catalog to discover tables and their schemas.\n\n" +
+			"Use 'dataset search' for keyword-based discovery across all tables, or\n" +
+			"'dataset search-by-contract' to find decoded tables for a specific contract address.",
 	}
 	cmd.AddCommand(newSearchCmd())
+	cmd.AddCommand(newSearchByContractCmd())
 	return cmd
 }

cmd/dataset/search.go

@@ -13,26 +13,31 @@ import (
 func newSearchCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "search",
-		Short: "Search for tables and datasets across the Dune catalog",
-		Long: "Natural-language table discovery across the Dune catalog. Use this command\n" +
-			"to find concrete table names for use in SQL queries.\n\n" +
-			"Filter by category (canonical for chain primitives, decoded for ABI-level\n" +
-			"events/calls, spell for curated datasets, community for user-contributed),\n" +
-			"by blockchain, schema, dataset type, or ownership scope.",
-		RunE:  runSearch,
+		Short: "Search for datasets across the Dune catalog",
+		Long: "Search for datasets across the Dune catalog by keyword, category, blockchain, and more.\n\n" +
+			"The catalog includes canonical blockchain data, decoded contract tables,\n" +
+			"Spellbook transformations, and community datasets. Use --include-schema\n" +
+			"to get column names and types for SQL generation.\n\n" +
+			"Examples:\n" +
+			"  dune dataset search --query \"uniswap swaps\"\n" +
+			"  dune dataset search --query \"transfers\" --categories decoded --blockchains ethereum\n" +
+			"  dune dataset search --query \"dex trades\" --categories spell --include-schema --output json\n" +
+			"  dune dataset search --owner-scope me",
+		RunE: runSearch,
 	}
 
-	cmd.Flags().String("query", "", "natural-language search intent or entity hints (e.g. 'uniswap v3 swaps'); use '*' to browse without keyword bias")
-	cmd.Flags().StringArray("categories", nil, "filter by table family: canonical (chain primitives), decoded (ABI-level events/calls), spell (curated datasets), community (user-contributed)")
-	cmd.Flags().StringArray("blockchains", nil, "chain scope to reduce ambiguity and improve ranking (e.g. ethereum, solana)")
-	cmd.Flags().StringArray("dataset-types", nil, "fine-grained dataset type filter: dune_table, decoded_table, spell, uploaded_table, transformation_table, transformation_view")
-	cmd.Flags().StringArray("schemas", nil, "schema/namespace constraint for high precision (e.g. dex, uniswap_v3_ethereum)")
-	cmd.Flags().String("owner-scope", "", "ownership filter: all, me, or team; does NOT automatically include private datasets")
-	cmd.Flags().Bool("include-private", false, "widen results to include private datasets visible to the authenticated user/team alongside public ones")
-	cmd.Flags().Bool("include-schema", false, "include column-level schema (name, type, nullable) for every result; useful when preparing SQL")
-	cmd.Flags().Bool("include-metadata", false, "include category-specific metadata (page_rank_score, description, abi_type, contract_name, project_name, etc.)")
-	cmd.Flags().Int32("limit", 20, "number of results per page; use 5-15 for quick checks, 20-50 for deeper exploration")
-	cmd.Flags().Int32("offset", 0, "pagination offset; use previous response pagination info for next page")
+	cmd.Flags().String("query", "", "search query text")
+	cmd.Flags().StringArray("categories", nil, "filter by category (canonical, decoded, spell, community)")
+	cmd.Flags().StringArray("blockchains", nil, "filter by blockchain")
+	cmd.Flags().StringArray("dataset-types", nil,
+		"filter by dataset type (dune_table, decoded_table, spell, uploaded_table, transformation_table, transformation_view)")
+	cmd.Flags().StringArray("schemas", nil, "filter by schema")
+	cmd.Flags().String("owner-scope", "", "ownership filter (all, me, team)")
+	cmd.Flags().Bool("include-private", false, "include private datasets")
+	cmd.Flags().Bool("include-schema", false, "include column schema in results")
+	cmd.Flags().Bool("include-metadata", false, "include metadata in results")
+	cmd.Flags().Int32("limit", 20, "maximum number of results")
+	cmd.Flags().Int32("offset", 0, "pagination offset")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd

cmd/dataset/search_by_contract.go

@@ -0,0 +1,116 @@
+package dataset
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/duneanalytics/cli/cmdutil"
+	"github.com/duneanalytics/cli/output"
+	"github.com/duneanalytics/duneapi-client-go/models"
+	"github.com/spf13/cobra"
+)
+
+func newSearchByContractCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "search-by-contract",
+		Short: "Search for decoded tables associated with a specific contract address",
+		Long: `Search for decoded tables (events and calls) associated with a specific contract address.
+
+This command finds all available decoded tables for a given smart contract address.
+Decoded tables contain blockchain data that has been parsed according to a contract's ABI,
+providing a structured view of contract interactions.
+
+Table types returned:
+  - Event tables: contain parsed event logs emitted by smart contracts
+  - Call tables: contain parsed function calls made to smart contracts
+
+When to use this command:
+  - You have a specific contract address (EVM or Tron) and want to find its decoded tables
+  - You want to analyze on-chain activity for a particular smart contract
+  - You need to find event or call tables for a known contract
+
+For broader table discovery by keyword or project name, use 'dune dataset search' instead.
+
+Examples:
+  dune dataset search-by-contract --contract-address 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984
+  dune dataset search-by-contract --contract-address 0x1f98... --blockchains ethereum --blockchains arbitrum
+  dune dataset search-by-contract --contract-address 0x1f98... --include-schema
+  dune dataset search-by-contract --contract-address 0x1f98... --limit 50 --offset 20`,
+		RunE: runSearchByContract,
+	}
+
+	cmd.Flags().String("contract-address", "",
+		"The contract address to search for. Accepts EVM addresses (starting with 0x) or Tron addresses. "+
+			"Example: '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984'.")
+	_ = cmd.MarkFlagRequired("contract-address")
+	cmd.Flags().StringArray("blockchains", nil,
+		"Filter results to specific blockchains (e.g. ethereum, arbitrum). "+
+			"Can be specified multiple times. If not provided, searches across all blockchains where the contract exists.")
+	cmd.Flags().Bool("include-schema", false,
+		"If set, include the column-level schema (name, type, nullable) for every result. "+
+			"Enable when preparing SQL generation.")
+	cmd.Flags().Int32("limit", 20,
+		"Maximum number of results to return. "+
+			"Use smaller values (5-10) for quick checks, larger values (50-100) for comprehensive discovery.")
+	cmd.Flags().Int32("offset", 0,
+		"Number of results to skip for pagination. Use for paginating through large result sets.")
+	output.AddFormatFlag(cmd, "text")
+
+	return cmd
+}
+
+func runSearchByContract(cmd *cobra.Command, _ []string) error {
+	client := cmdutil.ClientFromCmd(cmd)
+
+	contractAddress, _ := cmd.Flags().GetString("contract-address")
+
+	req := models.SearchDatasetsByContractAddressRequest{
+		ContractAddress: contractAddress,
+	}
+
+	if cmd.Flags().Changed("blockchains") {
+		v, _ := cmd.Flags().GetStringArray("blockchains")
+		req.Blockchains = v
+	}
+	if cmd.Flags().Changed("include-schema") {
+		v, _ := cmd.Flags().GetBool("include-schema")
+		req.IncludeSchema = &v
+	}
+	if cmd.Flags().Changed("limit") {
+		v, _ := cmd.Flags().GetInt32("limit")
+		req.Limit = &v
+	}
+	if cmd.Flags().Changed("offset") {
+		v, _ := cmd.Flags().GetInt32("offset")
+		req.Offset = &v
+	}
+
+	resp, err := client.SearchDatasetsByContractAddress(req)
+	if err != nil {
+		return err
+	}
+
+	w := cmd.OutOrStdout()
+	switch output.FormatFromCmd(cmd) {
+	case output.FormatJSON:
+		return output.PrintJSON(w, resp)
+	default:
+		columns := []string{"FULL_NAME", "CATEGORY", "DATASET_TYPE", "BLOCKCHAINS"}
+		rows := make([][]string, len(resp.Results))
+		for i, r := range resp.Results {
+			dt := ""
+			if r.DatasetType != nil {
+				dt = *r.DatasetType
+			}
+			rows[i] = []string{
+				r.FullName,
+				r.Category,
+				dt,
+				strings.Join(r.Blockchains, ", "),
+			}
+		}
+		output.PrintTable(w, columns, rows)
+		fmt.Fprintf(w, "\n%d of %d results\n", len(resp.Results), resp.Total)
+		return nil
+	}
+}

cmd/docs/search.go

@@ -13,10 +13,15 @@ const defaultMCPEndpoint = "https://docs.dune.com/mcp"
 
 func newSearchCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:         "search",
-		Short:       "Search the Dune documentation for guides, API references, and code examples",
-		Long: "Search across all Dune documentation pages including guides, API references,\n" +
-			"DuneSQL syntax, and code examples. Does not require authentication.",
+		Use:   "search",
+		Short: "Search the Dune documentation",
+		Long: "Search the official Dune documentation. No authentication required.\n\n" +
+			"Look up DuneSQL syntax, API references, table naming conventions,\n" +
+			"and Dune platform concepts.\n\n" +
+			"Examples:\n" +
+			"  dune docs search --query \"DuneSQL string functions\"\n" +
+			"  dune docs search --query \"execute query API\" --api-reference-only\n" +
+			"  dune docs search --query \"decoded tables\" --code-only",
 		Annotations: map[string]string{"skipAuth": "true"},
 		RunE:        runSearch,
 	}

cmd/execution/results.go

@@ -17,15 +17,19 @@ var PollInterval = 2 * time.Second
 func newResultsCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "results <execution-id>",
-		Short: "Get execution results for a query execution by execution ID",
-		Long: "Retrieve the results of a query execution. By default, waits for the execution\n" +
-			"to complete (up to the timeout) before returning results.\n\n" +
-			"Behavior:\n" +
-			"  1. Checks the current execution status\n" +
-			"  2. If still running: polls until complete or timeout is reached\n" +
-			"  3. If completed: returns the result data\n" +
-			"  4. If failed/cancelled: returns the error details\n\n" +
-			"Use --no-wait to return the current state immediately without polling.",
+		Short: "Fetch results of a query execution",
+		Long: "Fetch results of a query execution by its execution ID.\n\n" +
+			"Use this after submitting a query with --no-wait, or to re-fetch results from\n" +
+			"a completed execution. The command handles all execution states:\n" +
+			"  - Completed: displays result rows\n" +
+			"  - Pending/Executing: shows current state (re-run later)\n" +
+			"  - Failed: returns the error message\n" +
+			"  - Cancelled: returns cancellation notice\n\n" +
+			"Use --limit and --offset to paginate through large result sets.\n\n" +
+			"Examples:\n" +
+			"  dune execution results 01JXYZ...\n" +
+			"  dune execution results 01JXYZ... --limit 100 --offset 200\n" +
+			"  dune execution results 01JXYZ... --output json",
 		Args: cobra.ExactArgs(1),
 		RunE: runResults,
 	}

cmd/query/create.go

@@ -12,20 +12,21 @@ import (
 func newCreateCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
-		Short: "Create a new Dune query and return the query ID",
-		Long: "Create a new SQL query on Dune. Returns the query ID on success.\n\n" +
-			"The query is written in DuneSQL dialect. If the query targets tables with\n" +
-			"known partition columns, include a WHERE filter on those columns\n" +
-			"(e.g. WHERE block_date >= CURRENT_DATE - INTERVAL '7' DAY) to enable\n" +
-			"partition pruning and reduce query cost.",
-		RunE:  runCreate,
+		Short: "Create a new saved query",
+		Long: "Create a new saved DuneSQL query. Returns the numeric query ID on success.\n" +
+			"Use --temp to create a temporary query that won't appear in your saved queries list.\n\n" +
+			"Examples:\n" +
+			"  dune query create --name \"Recent Blocks\" --sql \"SELECT * FROM ethereum.blocks LIMIT 10\"\n" +
+			"  dune query create --name \"My Query\" --sql \"SELECT 1\" --private --description \"Test query\"\n" +
+			"  dune query create --name \"Throwaway\" --sql \"SELECT 1\" --temp",
+		RunE: runCreate,
 	}
 
-	cmd.Flags().String("name", "", "human-readable query title, max 600 characters (required)")
-	cmd.Flags().String("sql", "", "the SQL query text in DuneSQL dialect, max 500,000 characters (required)")
-	cmd.Flags().String("description", "", "short description of what the query does, max 1,000 characters")
-	cmd.Flags().Bool("private", false, "make the query private; may be forced by team privacy settings")
-	cmd.Flags().Bool("temp", false, "create a temporary query that won't appear in the dune.com library or be accessible when shared")
+	cmd.Flags().String("name", "", "query name (required)")
+	cmd.Flags().String("sql", "", "DuneSQL query text (required)")
+	cmd.Flags().String("description", "", "query description")
+	cmd.Flags().Bool("private", false, "make the query private")
+	cmd.Flags().Bool("temp", false, "create a temporary query (auto-deleted, not shown in your saved queries)")
 	_ = cmd.MarkFlagRequired("name")
 	_ = cmd.MarkFlagRequired("sql")
 	output.AddFormatFlag(cmd, "text")

cmd/query/query.go

@@ -6,7 +6,10 @@ import "github.com/spf13/cobra"
 func NewQueryCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "query",
-		Short: "Create, retrieve, update, execute, and archive Dune queries",
+		Short: "Manage Dune queries",
+		Long: "Create, retrieve, update, archive, and execute DuneSQL queries.\n\n" +
+			"Use 'query create' to save a reusable query, 'query run' to execute a saved query,\n" +
+			"or 'query run-sql' to execute raw DuneSQL without saving.",
 	}
 	cmd.AddCommand(newCreateCmd())
 	cmd.AddCommand(newGetCmd())

cmd/query/run.go

@@ -13,20 +13,24 @@ import (
 func newRunCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run <query-id>",
-		Short: "Execute a saved Dune query by its ID and display results",
-		Long: "Execute a saved Dune query by its numeric ID. By default, waits for the\n" +
-			"execution to complete and displays the result rows. Use --no-wait to submit\n" +
-			"the execution and exit immediately with just the execution ID.\n\n" +
-			"Credits are consumed based on actual compute resources used. Use --performance\n" +
-			"to select the engine size (medium or large).",
-		Args:  cobra.ExactArgs(1),
-		RunE:  runRun,
+		Short: "Execute a saved query and display results",
+		Long: "Execute a saved DuneSQL query by its numeric ID and display results.\n\n" +
+			"By default, polls every 5 seconds for up to ~5 minutes waiting for completion.\n" +
+			"Use --no-wait to submit the execution and exit immediately; then fetch\n" +
+			"results later with 'dune execution results <execution-id>'.\n\n" +
+			"Examples:\n" +
+			"  dune query run 12345\n" +
+			"  dune query run 12345 --param wallet=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --param days=30\n" +
+			"  dune query run 12345 --performance large --limit 100\n" +
+			"  dune query run 12345 --no-wait",
+		Args: cobra.ExactArgs(1),
+		RunE: runRun,
 	}
 
-	cmd.Flags().StringArray("param", nil, "typed query parameter in key=value format (repeatable); numbers are stringified, datetimes use YYYY-MM-DD HH:mm:ss")
-	cmd.Flags().String("performance", "medium", `engine size for the execution: "medium" (default) or "large"; credits are consumed based on actual compute resources used`)
-	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all)")
-	cmd.Flags().Bool("no-wait", false, "submit the execution and exit immediately, printing only the execution ID and state")
+	cmd.Flags().StringArray("param", nil, "query parameter in key=value format (repeatable)")
+	cmd.Flags().String("performance", "medium", `performance tier: "medium" (default) or "large" for higher compute resources`)
+	cmd.Flags().Int("limit", 0, "maximum number of rows to display (0 = all)")
+	cmd.Flags().Bool("no-wait", false, "submit execution and exit without waiting for results")
 	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
 	output.AddFormatFlag(cmd, "text")
 
@@ -106,4 +110,3 @@ func parseParams(raw []string) (map[string]any, error) {
 	}
 	return params, nil
 }
-

cmd/query/run_sql.go

@@ -10,21 +10,25 @@ import (
 func newRunSQLCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run-sql",
-		Short: "Execute a raw DuneSQL query and display results",
-		Long: "Execute an inline SQL statement in DuneSQL dialect without saving it as a\n" +
-			"query on Dune. By default, waits for completion and displays result rows.\n\n" +
-			"Use --no-wait to submit the execution and exit immediately with just the\n" +
-			"execution ID. Credits are consumed based on actual compute resources used.",
-		Args:  cobra.NoArgs,
-		RunE:  runRunSQL,
+		Short: "Execute raw DuneSQL and display results",
+		Long: "Execute a DuneSQL query directly without creating a saved query.\n" +
+			"Ideal for ad-hoc exploration and one-off analysis.\n\n" +
+			"By default, polls every 5 seconds for up to ~5 minutes waiting for completion.\n" +
+			"Use --no-wait to submit and exit immediately.\n\n" +
+			"Examples:\n" +
+			"  dune query run-sql --sql \"SELECT block_number, block_time FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5\"\n" +
+			"  dune query run-sql --sql \"SELECT * FROM ethereum.transactions WHERE block_number = {{block_num}}\" --param block_num=20000000\n" +
+			"  dune query run-sql --sql \"SELECT COUNT(*) FROM ethereum.transactions\" --performance large",
+		Args: cobra.NoArgs,
+		RunE: runRunSQL,
 	}
 
-	cmd.Flags().String("sql", "", "the SQL query text in DuneSQL dialect (required)")
+	cmd.Flags().String("sql", "", "DuneSQL query to execute (required)")
 	_ = cmd.MarkFlagRequired("sql")
-	cmd.Flags().StringArray("param", nil, "typed query parameter in key=value format (repeatable); numbers are stringified, datetimes use YYYY-MM-DD HH:mm:ss")
-	cmd.Flags().String("performance", "medium", `engine size for the execution: "medium" (default) or "large"; credits are consumed based on actual compute resources used`)
-	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all)")
-	cmd.Flags().Bool("no-wait", false, "submit the execution and exit immediately, printing only the execution ID and state")
+	cmd.Flags().StringArray("param", nil, "query parameter in key=value format (repeatable)")
+	cmd.Flags().String("performance", "medium", `performance tier: "medium" (default) or "large" for higher compute resources`)
+	cmd.Flags().Int("limit", 0, "maximum number of rows to display (0 = all)")
+	cmd.Flags().Bool("no-wait", false, "submit execution and exit without waiting for results")
 	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
 	output.AddFormatFlag(cmd, "text")