Add Sparkscan CLI with full command suite, tests, and release pipeline

Implements a CLI wrapping sparkscan-api-go for querying addresses, tokens,
transactions, and network stats on the Spark network. Includes mock-based
tests, goreleaser config, CI/CD workflows, and a curl-pipe installer.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Quantumlyy

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+# 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.
+
+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 -race ./...

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+# 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.
+
+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,25 @@
+# Binaries
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Local tools
+/bin/
+
+# CLI binary
+sparkscan-cli
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Environment
+.env
+
+# Conductor
+.context/

.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: sparkscan-cli
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - main: ./cmd
+    binary: sparkscan
+    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: refrakts
+    name: sparkscan-cli
+  draft: false
+  prerelease: auto
+  extra_files:
+    - glob: install.sh

Makefile

@@ -0,0 +1,57 @@
+# 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.
+
+.PHONY: all build test lint clean
+
+VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null | sed 's/^v//')
+COMMIT  ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null || echo "unknown")
+DATE    ?= $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')
+LDFLAGS  = -s -w \
+           -X main.version=$(VERSION) \
+           -X main.commit=$(COMMIT) \
+           -X main.date=$(DATE)
+
+all: lint test build
+
+build:
+	go build -ldflags '$(LDFLAGS)' -o bin/sparkscan ./cmd
+
+test:
+	go test -timeout=30s -race -cover ./...
+
+lint: bin/golangci-lint
+	go fmt ./...
+	go vet ./...
+	bin/golangci-lint -c .golangci.yml run ./...
+	go mod tidy
+
+run:
+	go run -ldflags '$(LDFLAGS)' ./cmd $(ARGS)
+
+bin:
+	mkdir -p bin
+
+bin/golangci-lint: bin
+	GOBIN=$(PWD)/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.8
+
+clean:
+	rm -rf bin/

cli/root.go

@@ -0,0 +1,77 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+
+	sparkscan "github.com/refrakts/sparkscan-api-go"
+	"github.com/spf13/cobra"
+
+	"github.com/refrakts/sparkscan-cli/cmd/address"
+	"github.com/refrakts/sparkscan-cli/cmd/stats"
+	"github.com/refrakts/sparkscan-cli/cmd/token"
+	"github.com/refrakts/sparkscan-cli/cmd/tx"
+	"github.com/refrakts/sparkscan-cli/cmd/version"
+	"github.com/refrakts/sparkscan-cli/cmdutil"
+	"github.com/refrakts/sparkscan-cli/output"
+)
+
+// NewRootCmd creates the root sparkscan command.
+func NewRootCmd(versionStr string) *cobra.Command {
+	root := &cobra.Command{
+		Use:           "sparkscan",
+		Short:         "CLI for the Sparkscan API",
+		Long:          "A command-line interface for the Sparkscan blockchain explorer API.\n\nQuery addresses, tokens, transactions, and network statistics on the Spark network.",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			if cmd.Annotations != nil && cmd.Annotations["skipClient"] == "true" {
+				return nil
+			}
+
+			apiKey, _ := cmd.Flags().GetString("api-key")
+			if apiKey == "" {
+				apiKey = os.Getenv("SPARKSCAN_API_KEY")
+			}
+
+			baseURL, _ := cmd.Flags().GetString("base-url")
+
+			var opts []sparkscan.Option
+			if apiKey != "" {
+				opts = append(opts, sparkscan.WithAPIKey(apiKey))
+			}
+
+			client, err := sparkscan.NewClient(baseURL, opts...)
+			if err != nil {
+				return fmt.Errorf("creating client: %w", err)
+			}
+
+			cmdutil.SetClient(cmd, client)
+			return nil
+		},
+	}
+
+	root.PersistentFlags().String("api-key", "", "Sparkscan API key (overrides SPARKSCAN_API_KEY)")
+	root.PersistentFlags().String("base-url", "https://api.sparkscan.io", "API base URL")
+	root.PersistentFlags().String("network", "MAINNET", "Network: MAINNET or REGTEST")
+	output.AddFormatFlag(root)
+
+	root.AddCommand(address.NewCmd())
+	root.AddCommand(token.NewCmd())
+	root.AddCommand(tx.NewCmd())
+	root.AddCommand(stats.NewCmd())
+	root.AddCommand(version.NewCmd(versionStr))
+
+	return root
+}
+
+// Execute runs the CLI.
+func Execute(version, commit, date string) {
+	versionStr := fmt.Sprintf("%s (commit: %s, built: %s)", version, commit, date)
+	root := NewRootCmd(versionStr)
+
+	if err := root.Execute(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

cmd/address/address.go

@@ -0,0 +1,16 @@
+package address
+
+import "github.com/spf13/cobra"
+
+// NewCmd returns the address parent command.
+func NewCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "address",
+		Short: "Query Spark addresses",
+	}
+	cmd.AddCommand(newGetCmd())
+	cmd.AddCommand(newTokensCmd())
+	cmd.AddCommand(newTransactionsCmd())
+	cmd.AddCommand(newHistoryCmd())
+	return cmd
+}

cmd/address/get.go

@@ -0,0 +1,50 @@
+package address
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/refrakts/sparkscan-api-go/ogen"
+	"github.com/spf13/cobra"
+
+	"github.com/refrakts/sparkscan-cli/cmdutil"
+	"github.com/refrakts/sparkscan-cli/output"
+)
+
+func newGetCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "get <address>",
+		Short: "Get address summary including balances and transaction count",
+		Args:  cobra.ExactArgs(1),
+		RunE:  runGet,
+	}
+}
+
+func runGet(cmd *cobra.Command, args []string) error {
+	client := cmdutil.ClientFromCmd(cmd)
+	network := cmdutil.NetworkFromCmd(cmd)
+
+	params := ogen.GetV1AddressByAddressParams{Address: args[0]}
+	if network != "" {
+		params.Network.SetTo(ogen.GetV1AddressByAddressNetwork(network))
+	}
+
+	resp, err := client.GetV1AddressByAddress(cmd.Context(), params)
+	if err != nil {
+		return err
+	}
+
+	return output.PrintResult(cmd, resp, func(w io.Writer) error {
+		fmt.Fprintf(w, "Spark Address:         %s\n", resp.SparkAddress)
+		fmt.Fprintf(w, "Public Key:            %s\n", resp.PublicKey)
+		fmt.Fprintf(w, "BTC Hard Balance:      %d sats\n", resp.Balance.BtcHardBalanceSats)
+		fmt.Fprintf(w, "BTC Soft Balance:      %d sats\n", resp.Balance.BtcSoftBalanceSats)
+		fmt.Fprintf(w, "BTC Value (Hard):      $%.2f\n", resp.Balance.BtcValueUsdHard)
+		fmt.Fprintf(w, "BTC Value (Soft):      $%.2f\n", resp.Balance.BtcValueUsdSoft)
+		fmt.Fprintf(w, "Token Value (USD):     $%.2f\n", resp.Balance.TotalTokenValueUsd)
+		fmt.Fprintf(w, "Total Value (USD):     $%.2f\n", resp.TotalValueUsd)
+		fmt.Fprintf(w, "Token Count:           %d\n", resp.TokenCount)
+		fmt.Fprintf(w, "Transaction Count:     %d\n", resp.TransactionCount)
+		return nil
+	})
+}