rich tool descriptions

ivpusic · ivpusic · commit ea255e4ca639 · 2026-03-05T10:35:59.000+01:00
diff --git a/cli/root.go b/cli/root.go
@@ -24,9 +24,12 @@ var apiKeyFlag string
 
 var rootCmd = &cobra.Command{
 	Use:   "dune",
-	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 them, and retrieve results.",
+	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`.",
 	PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
 		if cmd.Annotations["skipAuth"] == "true" {
 			return nil
diff --git a/cmd/dataset/dataset.go b/cmd/dataset/dataset.go
@@ -6,7 +6,7 @@ import "github.com/spf13/cobra"
 func NewDatasetCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "dataset",
-		Short: "Manage Dune datasets",
+		Short: "Discover and explore datasets across the Dune catalog",
 	}
 	cmd.AddCommand(newSearchCmd())
 	return cmd
diff --git a/cmd/dataset/search.go b/cmd/dataset/search.go
@@ -13,21 +13,26 @@ import (
 func newSearchCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "search",
-		Short: "Search for datasets across the Dune catalog",
+		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,
 	}
 
-	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")
-	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")
+	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")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd
diff --git a/cmd/docs/docs.go b/cmd/docs/docs.go
@@ -6,7 +6,7 @@ import "github.com/spf13/cobra"
 func NewDocsCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:         "docs",
-		Short:       "Search and browse Dune documentation",
+		Short:       "Search the Dune documentation for guides, API references, and examples",
 		Annotations: map[string]string{"skipAuth": "true"},
 	}
 	cmd.AddCommand(newSearchCmd())
diff --git a/cmd/docs/search.go b/cmd/docs/search.go
@@ -14,15 +14,17 @@ const defaultMCPEndpoint = "https://docs.dune.com/mcp"
 func newSearchCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:         "search",
-		Short:       "Search the Dune documentation",
+		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.",
 		Annotations: map[string]string{"skipAuth": "true"},
 		RunE:        runSearch,
 	}
 
-	cmd.Flags().String("query", "", "search query text (required)")
+	cmd.Flags().String("query", "", "search query text, e.g. 'DuneSQL date functions' or 'API authentication' (required)")
 	_ = cmd.MarkFlagRequired("query")
-	cmd.Flags().Bool("api-reference-only", false, "prioritize API reference pages")
-	cmd.Flags().Bool("code-only", false, "prioritize pages with code examples")
+	cmd.Flags().Bool("api-reference-only", false, "prioritize API reference pages over conceptual guides")
+	cmd.Flags().Bool("code-only", false, "prioritize pages with executable examples and code snippets")
 	cmd.Flags().String("mcp-endpoint", defaultMCPEndpoint, "MCP server endpoint URL")
 	_ = cmd.Flags().MarkHidden("mcp-endpoint")
 	output.AddFormatFlag(cmd, "text")
diff --git a/cmd/execution/execution.go b/cmd/execution/execution.go
@@ -6,7 +6,7 @@ import "github.com/spf13/cobra"
 func NewExecutionCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "execution",
-		Short: "Manage query executions",
+		Short: "Retrieve and inspect query execution results",
 	}
 	cmd.AddCommand(newResultsCmd())
 	return cmd
diff --git a/cmd/execution/results.go b/cmd/execution/results.go
@@ -17,15 +17,23 @@ var PollInterval = 2 * time.Second
 func newResultsCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "results <execution-id>",
-		Short: "Fetch results of a query execution",
+		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.",
 		Args:  cobra.ExactArgs(1),
 		RunE:  runResults,
 	}
 
-	cmd.Flags().Int("limit", 0, "maximum number of rows to return (0 = all)")
-	cmd.Flags().Int("offset", 0, "number of rows to skip")
-	cmd.Flags().Bool("no-wait", false, "fetch current state without waiting for completion")
-	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for completion")
+	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all)")
+	cmd.Flags().Int("offset", 0, "number of rows to skip before returning results, used for pagination")
+	cmd.Flags().Bool("no-wait", false, "return the current execution state immediately without waiting for completion")
+	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd
diff --git a/cmd/query/archive.go b/cmd/query/archive.go
@@ -11,7 +11,10 @@ import (
 func newArchiveCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "archive <query-id>",
-		Short: "Archive a saved query",
+		Short: "Archive a saved Dune query by ID",
+		Long: "Mark a Dune query as archived. Archived queries are hidden from the library\n" +
+			"but can still be retrieved by ID. You must own the query or have edit access\n" +
+			"via team membership.",
 		Args:  cobra.ExactArgs(1),
 		RunE:  runArchive,
 	}
diff --git a/cmd/query/create.go b/cmd/query/create.go
@@ -12,15 +12,20 @@ import (
 func newCreateCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
-		Short: "Create a new saved query",
+		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,
 	}
 
-	cmd.Flags().String("name", "", "query name (required)")
-	cmd.Flags().String("sql", "", "query SQL (required)")
-	cmd.Flags().String("description", "", "query description")
-	cmd.Flags().Bool("private", false, "make the query private")
-	cmd.Flags().Bool("temp", false, "create a temporary (unsaved) query")
+	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.MarkFlagRequired("name")
 	_ = cmd.MarkFlagRequired("sql")
 	output.AddFormatFlag(cmd, "text")
diff --git a/cmd/query/get.go b/cmd/query/get.go
@@ -12,7 +12,9 @@ import (
 func newGetCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "get <query-id>",
-		Short: "Get a saved query",
+		Short: "Fetch a saved Dune query by ID, including SQL and metadata",
+		Long: "Retrieve SQL, metadata, owner, privacy flags, tags, and execution state for\n" +
+			"an existing Dune query. Only queries visible to the authenticated user are returned.",
 		Args:  cobra.ExactArgs(1),
 		RunE:  runGet,
 	}
diff --git a/cmd/query/query.go b/cmd/query/query.go
@@ -6,7 +6,7 @@ import "github.com/spf13/cobra"
 func NewQueryCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "query",
-		Short: "Manage Dune queries",
+		Short: "Create, retrieve, update, execute, and archive Dune queries",
 	}
 	cmd.AddCommand(newCreateCmd())
 	cmd.AddCommand(newGetCmd())
diff --git a/cmd/query/run.go b/cmd/query/run.go
@@ -13,16 +13,21 @@ import (
 func newRunCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run <query-id>",
-		Short: "Execute a saved query and display results",
+		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,
 	}
 
-	cmd.Flags().StringArray("param", nil, "query parameter in key=value format (repeatable)")
-	cmd.Flags().String("performance", "medium", `performance tier: "medium" or "large"`)
-	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 completion")
+	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().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd
diff --git a/cmd/query/run_sql.go b/cmd/query/run_sql.go
@@ -10,18 +10,22 @@ import (
 func newRunSQLCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run-sql",
-		Short: "Execute raw SQL and display results",
+		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,
 	}
 
-	cmd.Flags().String("sql", "", "SQL query to execute (required)")
+	cmd.Flags().String("sql", "", "the SQL query text in DuneSQL dialect (required)")
 	_ = cmd.MarkFlagRequired("sql")
-	cmd.Flags().StringArray("param", nil, "query parameter in key=value format (repeatable)")
-	cmd.Flags().String("performance", "medium", `performance tier: "medium" or "large"`)
-	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 completion")
+	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().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd
diff --git a/cmd/query/update.go b/cmd/query/update.go
@@ -12,16 +12,20 @@ import (
 func newUpdateCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update <query-id>",
-		Short: "Update an existing saved query",
+		Short: "Update an existing Dune query's SQL, title, description, privacy, or tags",
+		Long: "Modify a query you own or have edit access to via team membership.\n" +
+			"Only supply the flags you want to change; unchanged fields are preserved.\n\n" +
+			"The update uses optimistic locking — if someone else edited the query\n" +
+			"concurrently, you'll get a conflict error.",
 		Args:  cobra.ExactArgs(1),
 		RunE:  runUpdate,
 	}
 
-	cmd.Flags().String("name", "", "query name")
-	cmd.Flags().String("sql", "", "query SQL")
-	cmd.Flags().String("description", "", "query description")
-	cmd.Flags().Bool("private", false, "make the query private")
-	cmd.Flags().StringSlice("tags", nil, "query tags (comma-separated)")
+	cmd.Flags().String("name", "", "new title for the query, max 600 characters")
+	cmd.Flags().String("sql", "", "new SQL content in DuneSQL dialect, max 500,000 characters")
+	cmd.Flags().String("description", "", "new description for the query, max 1,000 characters")
+	cmd.Flags().Bool("private", false, "set to true to make the query private, false to make public")
+	cmd.Flags().StringSlice("tags", nil, "new set of tags for the query (comma-separated); replaces all existing tags")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd
diff --git a/cmd/usage/usage.go b/cmd/usage/usage.go
@@ -14,12 +14,14 @@ import (
 func NewUsageCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "usage",
-		Short: "Show credit and resource usage for your Dune account",
+		Short: "Get credit and resource usage for the authenticated Dune account",
+		Long: "Show current-period credit usage, storage consumption, and billing period\n" +
+			"boundaries for the authenticated user or team. Optionally filter by date range.",
 		RunE:  runUsage,
 	}
 
-	cmd.Flags().String("start-date", "", "filter start date (YYYY-MM-DD)")
-	cmd.Flags().String("end-date", "", "filter end date (YYYY-MM-DD)")
+	cmd.Flags().String("start-date", "", "filter usage from this date (YYYY-MM-DD format)")
+	cmd.Flags().String("end-date", "", "filter usage up to this date (YYYY-MM-DD format)")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ import "github.com/spf13/cobra"`
`6`	`6`	`func NewDatasetCmd() *cobra.Command {`
`7`	`7`	`cmd := &cobra.Command{`
`8`	`8`	`Use: "dataset",`
`9`		`- Short: "Manage Dune datasets",`
	`9`	`+ Short: "Discover and explore datasets across the Dune catalog",`
`10`	`10`	`}`
`11`	`11`	`cmd.AddCommand(newSearchCmd())`
`12`	`12`	`return cmd`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ import "github.com/spf13/cobra"`
`6`	`6`	`func NewDocsCmd() *cobra.Command {`
`7`	`7`	`cmd := &cobra.Command{`
`8`	`8`	`Use: "docs",`
`9`		`- Short: "Search and browse Dune documentation",`
	`9`	`+ Short: "Search the Dune documentation for guides, API references, and examples",`
`10`	`10`	`Annotations: map[string]string{"skipAuth": "true"},`
`11`	`11`	`}`
`12`	`12`	`cmd.AddCommand(newSearchCmd())`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ import "github.com/spf13/cobra"`
`6`	`6`	`func NewExecutionCmd() *cobra.Command {`
`7`	`7`	`cmd := &cobra.Command{`
`8`	`8`	`Use: "execution",`
`9`		`- Short: "Manage query executions",`
	`9`	`+ Short: "Retrieve and inspect query execution results",`
`10`	`10`	`}`
`11`	`11`	`cmd.AddCommand(newResultsCmd())`
`12`	`12`	`return cmd`