case "xxhash":
		cmd.RunXXHash(os.Args[2:])
	case "metadata":
		cmd.RunMetadata(os.Args[2:])

	fmt.Fprintf(os.Stderr, "Usage: %s <command> --db <path> [options]\n\n", os.Args[0])

	fmt.Fprintf(os.Stderr, "Usage: %s <command> [options]\n\n", os.Args[0])

	fmt.Fprintf(os.Stderr, "  xxhash     Compute XXH64 hash of a file\n")
	fmt.Fprintf(os.Stderr, "  metadata   Extract WAV file metadata\n")

	fmt.Fprintf(os.Stderr, "  %s import bulk --db ./db/skraak.duckdb --dataset abc123 --csv import.csv --log progress.log\n", os.Args[0])

	fmt.Fprintf(os.Stderr, "  %s xxhash --file recording.wav\n", os.Args[0])
	fmt.Fprintf(os.Stderr, "  %s metadata --file recording.wav\n", os.Args[0])

package cmd
import (
	"encoding/json"
	"flag"
	"fmt"
	"os"
	"skraak/utils"
)
// RunXXHash handles the "xxhash" subcommand
func RunXXHash(args []string) {
	fs := flag.NewFlagSet("xxhash", flag.ExitOnError)
	filePath := fs.String("file", "", "Path to file (required)")
	fs.Usage = func() {
		fmt.Fprintf(os.Stderr, "Usage: skraak xxhash --file <path>\n\n")
		fmt.Fprintf(os.Stderr, "Compute XXH64 hash of a file (same format stored in database).\n\n")
		fmt.Fprintf(os.Stderr, "Options:\n")
		fs.PrintDefaults()
		fmt.Fprintf(os.Stderr, "\nExamples:\n")
		fmt.Fprintf(os.Stderr, "  skraak xxhash --file recording.wav\n")
		fmt.Fprintf(os.Stderr, "  skraak xxhash --file /path/to/audio.wav | jq '.hash'\n")
	}
	if err := fs.Parse(args); err != nil {
		os.Exit(1)
	}
	if *filePath == "" {
		fmt.Fprintf(os.Stderr, "Error: --file is required\n\n")
		fs.Usage()
		os.Exit(1)
	}
	// Compute hash
	hash, err := utils.ComputeXXH64(*filePath)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
		os.Exit(1)
	}
	// Output as JSON
	output := map[string]string{
		"file": *filePath,
		"hash": hash,
	}
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "  ")
	enc.Encode(output)
}

package cmd
import (
	"encoding/json"
	"flag"
	"fmt"
	"os"
	"skraak/utils"
)
// RunMetadata handles the "metadata" subcommand
func RunMetadata(args []string) {
	fs := flag.NewFlagSet("metadata", flag.ExitOnError)
	filePath := fs.String("file", "", "Path to WAV file (required)")
	fs.Usage = func() {
		fmt.Fprintf(os.Stderr, "Usage: skraak metadata --file <path>\n\n")
		fmt.Fprintf(os.Stderr, "Extract metadata from a WAV file header.\n\n")
		fmt.Fprintf(os.Stderr, "Options:\n")
		fs.PrintDefaults()
		fmt.Fprintf(os.Stderr, "\nExamples:\n")
		fmt.Fprintf(os.Stderr, "  skraak metadata --file recording.wav\n")
		fmt.Fprintf(os.Stderr, "  skraak metadata --file /path/to/audio.wav | jq '.duration_seconds'\n")
	}
	if err := fs.Parse(args); err != nil {
		os.Exit(1)
	}
	if *filePath == "" {
		fmt.Fprintf(os.Stderr, "Error: --file is required\n\n")
		fs.Usage()
		os.Exit(1)
	}
	// Parse WAV header
	metadata, err := utils.ParseWAVHeader(*filePath)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
		os.Exit(1)
	}
	// Output as JSON
	output := map[string]interface{}{
		"file":            *filePath,
		"duration_seconds": metadata.Duration,
		"sample_rate":      metadata.SampleRate,
		"channels":         metadata.Channels,
		"bits_per_sample":  metadata.BitsPerSample,
	}
	// Add optional fields if present
	if metadata.Comment != "" {
		output["comment"] = metadata.Comment
	}
	if metadata.Artist != "" {
		output["artist"] = metadata.Artist
	}
	if !metadata.FileModTime.IsZero() {
		output["file_mod_time"] = metadata.FileModTime.Format("2006-01-02T15:04:05Z07:00")
	}
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "  ")
	enc.Encode(output)
}

# File utilities
./skraak xxhash --file recording.wav     # XXH64 hash (same format as DB)
./skraak metadata --file recording.wav   # WAV metadata as JSON

- `xxhash` - Compute XXH64 hash of a file (JSON output)
- `metadata` - Extract WAV file metadata (JSON output)

# File utilities
./skraak xxhash --file recording.wav     # Compute XXH64 hash (same format as DB)
./skraak metadata --file recording.wav   # Extract WAV metadata
```
### CLI Design Policy
**All CLI tools MUST output JSON** for consistency and composability with Unix tools (jq, grep, etc.).
```bash
# JSON output allows piping to jq
./skraak xxhash --file recording.wav | jq '.hash'
./skraak metadata --file recording.wav | jq '.duration_seconds'
# JSON output allows chaining commands
HASH=$(./skraak xxhash --file recording.wav | jq -r '.hash')
DURATION=$(./skraak metadata --file recording.wav | jq -r '.duration_seconds')

**Exception**: Error messages go to stderr (not stdout) so they don't break JSON parsing.