fix(cli): allow --performance free for query run / run-sql

README.md

@@ -35,8 +35,8 @@ Manage and execute Dune queries.
 | `query get <query-id>` | Get a saved query's details and SQL |
 | `query update <query-id> [--name] [--sql] [--description] [--private] [--tags]` | Update an existing query |
 | `query archive <query-id>` | Archive a saved query |
-| `query run <query-id> [--param key=value] [--performance small\|medium\|large] [--limit] [--timeout] [--no-wait]` | Execute a saved query and display results |
-| `query run-sql --sql <sql> [--param key=value] [--performance small\|medium\|large] [--limit] [--timeout] [--no-wait]` | Execute raw SQL directly |
+| `query run <query-id> [--param key=value] [--performance free\|small\|medium\|large] [--limit] [--timeout] [--no-wait]` | Execute a saved query and display results |
+| `query run-sql --sql <sql> [--param key=value] [--performance free\|small\|medium\|large] [--limit] [--timeout] [--no-wait]` | Execute raw SQL directly |
 
 ### `dune execution`
 

cmd/query/helpers.go

@@ -22,13 +22,15 @@ func parseQueryID(arg string) (int, error) {
 
 func parsePerformance(cmd *cobra.Command) (string, error) {
 	performance, _ := cmd.Flags().GetString("performance")
-	if performance != "small" && performance != "medium" && performance != "large" {
+	switch performance {
+	case "small", "medium", "large", "free":
+		return performance, nil
+	default:
 		return "", fmt.Errorf(
-			"invalid performance tier %q: must be \"small\", \"medium\" or \"large\"",
+			"invalid performance tier %q: must be \"free\", \"small\", \"medium\" or \"large\"",
 			performance,
 		)
 	}
-	return performance, nil
 }
 
 func waitAndDisplay(cmd *cobra.Command, exec dune.Execution, timeout int) error {

cmd/query/run.go

@@ -19,7 +19,7 @@ func newRunCmd() *cobra.Command {
 			"Use --no-wait to submit the execution and exit immediately with just the\n" +
 			"execution ID; then fetch results later with 'dune execution results <execution-id>'.\n\n" +
 			"Credits are consumed based on actual compute resources used. Use --performance\n" +
-			"to select the engine size (medium or large).\n\n" +
+			"with the tier name your plan exposes via the API (e.g. community plans often use \"free\").\n\n" +
 			"Important: if the query targets tables with known partition columns (returned by\n" +
 			"'dune dataset search' or 'dune dataset search-by-contract'), ensure the SQL includes\n" +
 			"a WHERE filter on those partition columns (e.g. WHERE block_date >= CURRENT_DATE -\n" +
@@ -35,7 +35,7 @@ func newRunCmd() *cobra.Command {
 	}
 
 	cmd.Flags().StringArray("param", nil, "typed query parameter in key=value format (repeatable); supported types: text, number (stringified, e.g. '30'), datetime (YYYY-MM-DD HH:mm:ss), enum")
-	cmd.Flags().String("performance", "medium", `engine size for the execution: "small", "medium" (default) or "large"; credits are consumed based on actual compute resources used`)
+	cmd.Flags().String("performance", "medium", `engine tier name (plan-specific; community often uses "free"): "free", "small", "medium" (default), or "large"; credits reflect actual compute`)
 	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all available rows)")
 	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")

cmd/query/run_sql.go

@@ -36,7 +36,7 @@ func newRunSQLCmd() *cobra.Command {
 	cmd.Flags().String("sql", "", "the SQL query text in DuneSQL dialect (required)")
 	_ = cmd.MarkFlagRequired("sql")
 	cmd.Flags().StringArray("param", nil, "typed query parameter in key=value format (repeatable); supported types: text, number (stringified, e.g. '30'), datetime (YYYY-MM-DD HH:mm:ss), enum")
-	cmd.Flags().String("performance", "medium", `engine size for the execution: "small", "medium" (default) or "large"; credits are consumed based on actual compute resources used`)
+	cmd.Flags().String("performance", "medium", `engine tier name for the execution (plan-specific; community often uses "free"): "free", "small", "medium" (default), or "large"; credits reflect actual compute`)
 	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all available rows)")
 	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")

cmd/query/run_sql_test.go

@@ -112,6 +112,27 @@ func TestRunSQLWithPerformance(t *testing.T) {
 	assert.Equal(t, "large", captured.Performance)
 }
 
+func TestRunSQLWithPerformanceFree(t *testing.T) {
+	var captured models.ExecuteSQLRequest
+	mock := &mockClient{
+		runSQLFn: func(req models.ExecuteSQLRequest) (dune.Execution, error) {
+			captured = req
+			return &mockExecution{
+				id: "01ABC",
+				waitGetResultsFn: func(_ time.Duration, _ int) (*models.ResultsResponse, error) {
+					return testResultsResponse, nil
+				},
+			}, nil
+		},
+	}
+
+	root, _ := newTestRoot(mock)
+	root.SetArgs([]string{"query", "run-sql", "--sql", "SELECT 1", "--performance", "free"})
+	require.NoError(t, root.Execute())
+
+	assert.Equal(t, "free", captured.Performance)
+}
+
 func TestRunSQLExecutionFailed(t *testing.T) {
 	failedResp := &models.ResultsResponse{
 		QueryID: 4125432,