Dune CLI

Author: ivpusic

.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - run: go test ./...

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          distribution: goreleaser
+          version: "~> v2"
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,18 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Local tools
+/bin/
+
+# CLI binary
+dune-cli

.golangci.yml

@@ -0,0 +1,17 @@
+---
+linters:
+  enable:
+    - goimports
+    - stylecheck
+    - lll
+  disable:
+    - errcheck
+
+run:
+  go: '1.25'
+
+issues:
+  exclude-rules:
+    - linters:
+        - lll
+      source: "// nolint:lll"

.goreleaser.yml

@@ -0,0 +1,56 @@
+version: 2
+
+project_name: dune-cli
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - main: ./cmd
+    binary: dune
+    env:
+      - CGO_ENABLED=0
+    ldflags:
+      - -s -w
+      - -X main.version={{.Version}}
+      - -X main.commit={{.Commit}}
+      - -X main.date={{.Date}}
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
+
+archives:
+  - formats:
+      - tar.gz
+    name_template: >-
+      {{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}
+    format_overrides:
+      - goos: windows
+        formats:
+          - zip
+
+checksum:
+  name_template: "checksums.txt"
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"
+      - "^ci:"
+      - "^chore:"
+
+release:
+  github:
+    owner: duneanalytics
+    name: cli
+  draft: false
+  prerelease: auto
+  extra_files:
+    - glob: install.sh

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dune Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,72 @@
+# Dune CLI
+
+A command-line interface for interacting with the Dune Analytics API.
+
+## Authentication
+
+```bash
+# Save your API key to ~/.config/dune/config.yaml
+dune auth --api-key <key>
+
+# Or run interactively (prompts for key)
+dune auth
+
+# Or set via environment variable
+export DUNE_API_KEY=<key>
+```
+
+The `--api-key` flag is available on all commands to override the stored key.
+
+## Commands
+
+### `dune query`
+
+Manage and execute Dune queries.
+
+| Command | Description |
+|---------|-------------|
+| `query create --name <name> --sql <sql> [--description] [--private] [--temp]` | Create a new saved query |
+| `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 medium\|large] [--limit] [--timeout] [--no-wait]` | Execute a saved query and display results |
+| `query run-sql --sql <sql> [--param key=value] [--performance medium\|large] [--limit] [--timeout] [--no-wait]` | Execute raw SQL directly |
+
+### `dune execution`
+
+Manage query executions.
+
+| Command | Description |
+|---------|-------------|
+| `execution results <execution-id> [--limit] [--offset] [--timeout] [--no-wait]` | Fetch results of a query execution |
+
+### `dune dataset`
+
+Search the Dune dataset catalog.
+
+| Command | Description |
+|---------|-------------|
+| `dataset search [--query] [--categories] [--blockchains] [--schemas] [--dataset-types] [--owner-scope] [--include-private] [--include-schema] [--include-metadata] [--limit] [--offset]` | Search for datasets |
+| `dataset search-by-contract --contract-address <address> [--blockchains] [--include-schema] [--limit] [--offset]` | Search for decoded tables by contract address |
+
+Categories: `canonical`, `decoded`, `spell`, `community`
+
+### `dune docs`
+
+Search and browse Dune documentation. No authentication required.
+
+| Command | Description |
+|---------|-------------|
+| `docs search --query <text> [--api-reference-only] [--code-only]` | Search the Dune documentation |
+
+### `dune usage`
+
+Show credit and resource usage for your account.
+
+```bash
+dune usage [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]
+```
+
+## Output Format
+
+All commands (except `auth`) support `-o, --output <format>` with `text` (default) or `json`.

authconfig/authconfig.go

@@ -0,0 +1,101 @@
+package authconfig
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Config holds the persisted CLI configuration.
+type Config struct {
+	APIKey string `yaml:"api_key"`
+}
+
+// configDirFunc allows tests to override the config directory.
+var (
+	configDirFunc = defaultDir
+	configMu      sync.RWMutex
+)
+
+func defaultDir() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(home, ".config", "dune"), nil
+}
+
+// SetDirFunc overrides the config directory function (for testing).
+func SetDirFunc(fn func() (string, error)) {
+	configMu.Lock()
+	defer configMu.Unlock()
+	configDirFunc = fn
+}
+
+// ResetDirFunc restores the default config directory function.
+func ResetDirFunc() {
+	configMu.Lock()
+	defer configMu.Unlock()
+	configDirFunc = defaultDir
+}
+
+// Dir returns the config directory path ($HOME/.config/dune).
+func Dir() (string, error) {
+	configMu.RLock()
+	defer configMu.RUnlock()
+	return configDirFunc()
+}
+
+// Path returns the full path to the config file.
+func Path() (string, error) {
+	dir, err := Dir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, "config.yaml"), nil
+}
+
+// Load reads and parses the config file. Returns nil, nil if the file does not exist.
+func Load() (*Config, error) {
+	p, err := Path()
+	if err != nil {
+		return nil, err
+	}
+
+	data, err := os.ReadFile(p)
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return nil, nil
+		}
+		return nil, err
+	}
+
+	var cfg Config
+	if err := yaml.Unmarshal(data, &cfg); err != nil {
+		return nil, err
+	}
+	return &cfg, nil
+}
+
+// Save writes the config to disk, creating the directory (0700) and file (0600) as needed.
+func Save(cfg *Config) error {
+	p, err := Path()
+	if err != nil {
+		return err
+	}
+
+	if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+		return err
+	}
+
+	data, err := yaml.Marshal(cfg)
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(p, data, 0o600)
+}