Timeout and help improvements

[ivpusic]

Added --timeout option and improved command and option descriptions to be more agent friendly.

[cursor]

PR Summary

Medium Risk
Changes execution-wait behavior and introduces polling/timeout logic, which can affect CLI responsiveness and API call patterns (potential rate limiting) if misconfigured.

Overview
Adds --timeout (default 300s) and polling/wait semantics to execution results, plus --no-wait to return the current state immediately; includes new tests covering polling success/failure/timeout and API errors.

Extends query run and query run-sql waiting behavior to accept a timeout (and retunes retry interval to 2s), and broadly rewrites command/flag descriptions across root, dataset, docs, query, and usage commands to be more explicit and agent-friendly.

^{Written by Cursor Bugbot for commit ea255e4. Configure here.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d83369c4-1fdf-457e-b78e-10c4c8481e2a

📥 Commits

Reviewing files that changed from the base of the PR and between ea255e4 and a6749d0.

📒 Files selected for processing (2)

• cmd/execution/results.go
• cmd/execution/results_test.go

---

📝 Walkthrough

Walkthrough

Updated CLI command metadata and help text across many commands; added configurable timeout, --no-wait, and polling behavior for execution results; wired timeout through SQL and query run flows; added PollInterval and centralized results handling; test coverage updated for no-wait and polling scenarios.

Changes

Cohort / File(s)	Summary
Root CLI Metadata cli/root.go	Updated root command Short and Long descriptions to describe platform usage, dataset discovery, DuneSQL queries, result retrieval, saved queries, and auth.
Dataset Discovery cmd/dataset/dataset.go, cmd/dataset/search.go	Refined help text; expanded search flags and descriptions (natural-language query, categories, blockchains, dataset-types, schemas, owner-scope, include-private/schema/metadata, limit/offset).
Documentation Search cmd/docs/docs.go, cmd/docs/search.go	Clarified Short/Long descriptions and query/priority flag semantics (api-reference-only, code-only).
Execution Commands & Results cmd/execution/execution.go, cmd/execution/results.go, cmd/execution/results_test.go	Added PollInterval var, --no-wait and --timeout behavior, polling loop via WaitGetResults, centralized handleResultsResponse, and expanded tests for no-wait, polling completion/failure, retries, and API errors.
Query Commands: create/get/update/archive cmd/query/create.go, cmd/query/get.go, cmd/query/update.go, cmd/query/archive.go, cmd/query/query.go	Extended Short/Long descriptions and reworded flag help texts (limits, SQL dialect, privacy, tags, visibility).
Query Run / SQL Execution cmd/query/run.go, cmd/query/run_sql.go, cmd/query/helpers.go	Added --timeout flag (default 300), threaded timeout through runWait/runSQLWait/waitAndDisplay signatures, changed no-wait vs wait execution paths, and adjusted retry/wait calculations to depend on timeout.
Account Usage cmd/usage/usage.go	Expanded Short/Long descriptions and clarified start/end date flag wording for usage queries.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as CLI (user)
    participant Cmd as Command Logic
    participant SDK as Dune Client (SDK)
    participant API as Dune API
    CLI->>Cmd: run results command (--no-wait / --timeout)
    Cmd->>SDK: Request execution results (QueryExecute or RunQuery)
    SDK->>API: HTTP call to results endpoint /execute
    API-->>SDK: Returns execution state (PENDING / EXECUTING / COMPLETED / FAILED)
    alt wait mode (no --no-wait is false)
        loop poll until timeout or COMPLETED
            Cmd->>SDK: WaitGetResults (poll)
            SDK->>API: Poll results endpoint
            API-->>SDK: Updated state
        end
        SDK-->>Cmd: Final results or error
    else no-wait
        SDK-->>Cmd: Immediate response (current state / partial results)
    end
    Cmd->>CLI: Render results / error via handleResultsResponse

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Dataset search command APP-7392 #11: Related changes to dataset command and search flags introduced earlier; overlaps with dataset/search refinements in this PR.
• Add query CRUD endpoints and refactor execution methods to use request structs APP-7343 duneapi-client-go#16: Refactor of execution methods and request structs that align with CLI changes to QueryExecute/RunQuery and timeout wiring.

Suggested reviewers

• va3093
• norbertdurcansk

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 13.16% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Timeout and help improvements' accurately reflects the main changes: adding --timeout functionality and improving command/flag descriptions throughout the CLI.
Description check	✅ Passed	The description 'Added --timeout option and improved command and option descriptions to be more agent friendly' directly relates to the changeset and captures both the timeout feature addition and the help text improvements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.5.0)

Error: can't load config: unsupported version of the configuration: "" See https://golangci-lint.run/docs/product/migration-guide for migration instructions
The command is terminated due to an error: can't load config: unsupported version of the configuration: "" See https://golangci-lint.run/docs/product/migration-guide for migration instructions

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}