Revamp --help command with comprehensive documentation

- Add detailed help system with main help and per-command help screens
- Support both -h and --help flags globally and per-command
- Document all features, flags, and requirements clearly
- Include practical examples for each command
- Add supported/unsupported content types for playlist command
- Provide installation instructions and troubleshooting tips
- Add step-by-step API setup guide in config help

The help system now provides complete documentation matching
all features described in the README, making the CLI more
user-friendly and self-documenting.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: guitaripod

main.go

@@ -16,6 +16,8 @@ var (
 	xFlag = flag.Bool("x", false, "Return the song.link URL without surrounding <>")
 	dFlag = flag.Bool("d", false, "Return the song.link URL surrounded by <> and the Spotify URL")
 	sFlag = flag.Bool("s", false, "Return only the Spotify URL")
+	hFlag = flag.Bool("h", false, "Show help information")
+	helpFlag = flag.Bool("help", false, "Show help information")
 )
 
 // Command represents a CLI command
@@ -53,6 +55,12 @@ func main() {
 	// Define base flags
 	flag.Parse()
 
+	// Check for help flags
+	if *hFlag || *helpFlag {
+		printHelp("")
+		os.Exit(0)
+	}
+
 	// Check if a subcommand is provided
 	args := flag.Args()
 	if len(args) > 0 {
@@ -70,9 +78,15 @@ func main() {
 			}
 		}
 
+		// Check if asking for help on a subcommand
+		if subcommand == "help" && len(args) > 1 {
+			printHelp(args[1])
+			os.Exit(0)
+		}
+		
 		// If we get here, the subcommand wasn't recognized
 		fmt.Printf("Unknown command: %s\n\n", subcommand)
-		printUsage()
+		printHelp("")
 		os.Exit(1)
 	}
 
@@ -91,12 +105,20 @@ func executeSearch(args []string) error {
    typeFlag := searchCmd.String("type", "song", "Type of search: song, album, or both (default: song)")
    outFlag := searchCmd.String("out", "downloads", "Output directory for downloaded files")
    debugFlag := searchCmd.Bool("debug", false, "Enable debug logging during download")
+   helpFlag := searchCmd.Bool("help", false, "Show help for search command")
+   hFlag := searchCmd.Bool("h", false, "Show help for search command")
 
 	// Parse search flags
 	if err := searchCmd.Parse(args); err != nil {
 		return err
 	}
 
+	// Check for help
+	if *helpFlag || *hFlag {
+		printSearchHelp()
+		os.Exit(0)
+	}
+	
 	// Get search query
 	searchArgs := searchCmd.Args()
 	if len(searchArgs) == 0 {
@@ -123,6 +145,22 @@ func executeSearch(args []string) error {
 
 // executeConfig handles the config subcommand
 func executeConfig(args []string) error {
+	// Define config flags
+	configCmd := flag.NewFlagSet("config", flag.ExitOnError)
+	helpFlag := configCmd.Bool("help", false, "Show help for config command")
+	hFlag := configCmd.Bool("h", false, "Show help for config command")
+	
+	// Parse flags
+	if err := configCmd.Parse(args); err != nil {
+		return err
+	}
+	
+	// Check for help
+	if *helpFlag || *hFlag {
+		printConfigHelp()
+		os.Exit(0)
+	}
+	
 	fmt.Println("Configuring Apple Music API credentials...")
    return RunOnboarding()
 }
@@ -135,11 +173,19 @@ func executeDownload(args []string) error {
    formatFlag := downloadCmd.String("format", "mp3", "Download format: mp3 or mp4 (default: mp3)")
    outFlag := downloadCmd.String("out", "downloads", "Output directory for downloaded files")
    debugFlag := downloadCmd.Bool("debug", false, "Enable debug logging (show yt-dlp/ffmpeg output)")
+   helpFlag := downloadCmd.Bool("help", false, "Show help for download command")
+   hFlag := downloadCmd.Bool("h", false, "Show help for download command")
 
    // Parse flags
    if err := downloadCmd.Parse(args); err != nil {
        return err
    }
+   
+   // Check for help
+   if *helpFlag || *hFlag {
+       printDownloadHelp()
+       os.Exit(0)
+   }
 
    // Get search query
    queryArgs := downloadCmd.Args()
@@ -215,11 +261,19 @@ func executePlaylist(args []string) error {
 	concurrentFlag := playlistCmd.Int("concurrent", 3, "Number of parallel downloads (default: 3)")
 	metadataFlag := playlistCmd.Bool("metadata", false, "Save playlist metadata JSON")
 	debugFlag := playlistCmd.Bool("debug", false, "Enable debug logging")
+	helpFlag := playlistCmd.Bool("help", false, "Show help for playlist command")
+	hFlag := playlistCmd.Bool("h", false, "Show help for playlist command")
 
 	// Parse flags
 	if err := playlistCmd.Parse(args); err != nil {
 		return err
 	}
+	
+	// Check for help
+	if *helpFlag || *hFlag {
+		printPlaylistHelp()
+		os.Exit(0)
+	}
 
 	// Get URL argument
 	urlArgs := playlistCmd.Args()
@@ -388,26 +442,218 @@ func runDefault() error {
 	return nil
 }
 
-// printUsage prints usage information
-func printUsage() {
-	fmt.Println("Usage:")
-	fmt.Println("  songlink-cli [flags]                 Process URL from clipboard")
-	fmt.Println("  songlink-cli search [flags] <query>  Search for a song or album")
-	fmt.Println("  songlink-cli config                  Configure Apple Music API credentials")
-	fmt.Println("  songlink-cli download [flags] <query> Download a song or album")
-	fmt.Println("  songlink-cli playlist [flags] <url>  Download entire playlist/album")
-	fmt.Println("\nFlags:")
-	fmt.Println("  -x  Return the song.link URL without surrounding <>")
-	fmt.Println("  -d  Return the song.link URL surrounded by <> and the Spotify URL")
-	fmt.Println("  -s  Return only the Spotify URL")
-	fmt.Println("\nSearch Flags:")
-	fmt.Println("  -type=<type>  Type of search: song, album, or both (default: song)")
-	fmt.Println("\nPlaylist Flags:")
-	fmt.Println("  --format=<fmt>    Download format: mp3 or mp4 (default: mp3)")
-	fmt.Println("  --out=<dir>       Output directory (default: downloads)")
-	fmt.Println("  --concurrent=<n>  Number of parallel downloads (default: 3)")
-	fmt.Println("  --metadata        Save playlist metadata JSON")
-	fmt.Println("  --debug           Show debug output")
+// printHelp prints comprehensive help information
+func printHelp(command string) {
+	switch command {
+	case "search":
+		printSearchHelp()
+	case "download":
+		printDownloadHelp()
+	case "playlist":
+		printPlaylistHelp()
+	case "config":
+		printConfigHelp()
+	default:
+		printGeneralHelp()
+	}
+}
+
+// printGeneralHelp prints the main help screen
+func printGeneralHelp() {
+	fmt.Println("Songlink CLI - A powerful tool for music sharing and downloading")
+	fmt.Println("")
+	fmt.Println("USAGE:")
+	fmt.Println("  songlink-cli [flags]                    Process URL from clipboard")
+	fmt.Println("  songlink-cli <command> [flags] <args>   Run a specific command")
+	fmt.Println("  songlink-cli help <command>             Show help for a command")
+	fmt.Println("")
+	fmt.Println("COMMANDS:")
+	fmt.Println("  search     Search for songs/albums and get shareable links")
+	fmt.Println("  download   Search and download tracks as MP3 or MP4 files")
+	fmt.Println("  playlist   Download entire playlists or albums from Apple Music")
+	fmt.Println("  config     Configure Apple Music API credentials")
+	fmt.Println("")
+	fmt.Println("GLOBAL FLAGS:")
+	fmt.Println("  -h, --help   Show this help message")
+	fmt.Println("")
+	fmt.Println("URL PROCESSING FLAGS (when run without command):")
+	fmt.Println("  -x   Return song.link URL without <> brackets (for Twitter)")
+	fmt.Println("  -d   Return song.link URL with <> + Spotify URL (for Discord)")
+	fmt.Println("  -s   Return only the Spotify URL")
+	fmt.Println("")
+	fmt.Println("EXAMPLES:")
+	fmt.Println("  # Process URL from clipboard (default)")
+	fmt.Println("  songlink-cli")
+	fmt.Println("")
+	fmt.Println("  # Get link for Twitter sharing")
+	fmt.Println("  songlink-cli -x")
+	fmt.Println("")
+	fmt.Println("  # Search for a song")
+	fmt.Println("  songlink-cli search \"Bohemian Rhapsody\"")
+	fmt.Println("")
+	fmt.Println("  # Download a track as MP4 with artwork")
+	fmt.Println("  songlink-cli download -format=mp4 \"Purple Rain\"")
+	fmt.Println("")
+	fmt.Println("  # Download an entire album")
+	fmt.Println("  songlink-cli playlist \"https://music.apple.com/us/album/...\"")
+	fmt.Println("")
+	fmt.Println("For more information on a command, run:")
+	fmt.Println("  songlink-cli help <command>")
+}
+
+// printSearchHelp prints help for the search command
+func printSearchHelp() {
+	fmt.Println("songlink-cli search - Search for songs or albums and get shareable links")
+	fmt.Println("")
+	fmt.Println("USAGE:")
+	fmt.Println("  songlink-cli search [flags] <query>")
+	fmt.Println("")
+	fmt.Println("DESCRIPTION:")
+	fmt.Println("  Search Apple Music for songs or albums and interactively select a result.")
+	fmt.Println("  After selection, you can choose to:")
+	fmt.Println("    1) Copy shareable links to clipboard")
+	fmt.Println("    2) Download the track as MP3")
+	fmt.Println("    3) Download as MP4 video with album artwork")
+	fmt.Println("")
+	fmt.Println("FLAGS:")
+	fmt.Println("  -type=<type>   Search type: song, album, or both (default: song)")
+	fmt.Println("  -out=<dir>     Output directory for downloads (default: downloads)")
+	fmt.Println("  -debug         Enable debug logging during download")
+	fmt.Println("")
+	fmt.Println("GLOBAL FLAGS (when copying links):")
+	fmt.Println("  -x             Format link for Twitter (no brackets)")
+	fmt.Println("  -d             Format for Discord (with Spotify URL)")
+	fmt.Println("  -s             Copy only Spotify URL")
+	fmt.Println("")
+	fmt.Println("EXAMPLES:")
+	fmt.Println("  # Search for a song")
+	fmt.Println("  songlink-cli search \"Imagine\"")
+	fmt.Println("")
+	fmt.Println("  # Search for albums only")
+	fmt.Println("  songlink-cli search -type=album \"Dark Side of the Moon\"")
+	fmt.Println("")
+	fmt.Println("  # Search and format for Discord")
+	fmt.Println("  songlink-cli search -d \"Hotel California\"")
+	fmt.Println("")
+	fmt.Println("REQUIREMENTS:")
+	fmt.Println("  - Apple Music API credentials (run 'songlink-cli config' to set up)")
+	fmt.Println("  - For downloads: yt-dlp and ffmpeg must be installed")
+}
+
+// printDownloadHelp prints help for the download command
+func printDownloadHelp() {
+	fmt.Println("songlink-cli download - Search and download tracks directly")
+	fmt.Println("")
+	fmt.Println("USAGE:")
+	fmt.Println("  songlink-cli download [flags] <query>")
+	fmt.Println("")
+	fmt.Println("DESCRIPTION:")
+	fmt.Println("  Search for a song or album and download it immediately as an audio")
+	fmt.Println("  file (MP3) or video file with album artwork (MP4). This command")
+	fmt.Println("  combines search and download into a single step.")
+	fmt.Println("")
+	fmt.Println("FLAGS:")
+	fmt.Println("  -type=<type>     Search type: song or album (default: song)")
+	fmt.Println("  -format=<fmt>    Download format: mp3 or mp4 (default: mp3)")
+	fmt.Println("  -out=<dir>       Output directory (default: downloads)")
+	fmt.Println("  -debug           Show yt-dlp and ffmpeg output")
+	fmt.Println("")
+	fmt.Println("EXAMPLES:")
+	fmt.Println("  # Download a song as MP3")
+	fmt.Println("  songlink-cli download \"Stairway to Heaven\"")
+	fmt.Println("")
+	fmt.Println("  # Download as MP4 with album artwork")
+	fmt.Println("  songlink-cli download -format=mp4 \"Wonderwall\"")
+	fmt.Println("")
+	fmt.Println("  # Download to custom directory")
+	fmt.Println("  songlink-cli download -out=~/Music \"Yesterday\"")
+	fmt.Println("")
+	fmt.Println("REQUIREMENTS:")
+	fmt.Println("  - Apple Music API credentials (run 'songlink-cli config' to set up)")
+	fmt.Println("  - yt-dlp: For downloading audio from YouTube")
+	fmt.Println("  - ffmpeg: For audio/video processing")
+	fmt.Println("")
+	fmt.Println("INSTALLATION (macOS):")
+	fmt.Println("  brew install yt-dlp ffmpeg")
+}
+
+// printPlaylistHelp prints help for the playlist command
+func printPlaylistHelp() {
+	fmt.Println("songlink-cli playlist - Download entire playlists or albums")
+	fmt.Println("")
+	fmt.Println("USAGE:")
+	fmt.Println("  songlink-cli playlist [flags] <apple-music-url>")
+	fmt.Println("")
+	fmt.Println("DESCRIPTION:")
+	fmt.Println("  Download all tracks from an Apple Music playlist or album URL.")
+	fmt.Println("  Supports parallel downloads and automatic retry on failures.")
+	fmt.Println("")
+	fmt.Println("SUPPORTED CONTENT:")
+	fmt.Println("  ✓ Public catalog albums")
+	fmt.Println("  ✓ Public catalog playlists")
+	fmt.Println("  ✗ Personal library playlists")
+	fmt.Println("  ✗ User-created playlists")
+	fmt.Println("  ✗ Radio stations")
+	fmt.Println("")
+	fmt.Println("FLAGS:")
+	fmt.Println("  --format=<fmt>      Download format: mp3 or mp4 (default: mp3)")
+	fmt.Println("  --out=<dir>         Output directory (default: downloads)")
+	fmt.Println("  --concurrent=<n>    Parallel downloads, 1-10 (default: 3)")
+	fmt.Println("  --metadata          Save playlist/album info as JSON")
+	fmt.Println("  --debug             Show detailed progress and errors")
+	fmt.Println("")
+	fmt.Println("EXAMPLES:")
+	fmt.Println("  # Download an album")
+	fmt.Println("  songlink-cli playlist \"https://music.apple.com/us/album/abbey-road/401469823\"")
+	fmt.Println("")
+	fmt.Println("  # Download playlist with metadata")
+	fmt.Println("  songlink-cli playlist --metadata \"https://music.apple.com/playlist/...\"")
+	fmt.Println("")
+	fmt.Println("  # Fast download with 5 workers")
+	fmt.Println("  songlink-cli playlist --concurrent=5 --format=mp4 \"https://...\"")
+	fmt.Println("")
+	fmt.Println("FEATURES:")
+	fmt.Println("  - Progress tracking for each download")
+	fmt.Println("  - Automatic retry with exponential backoff")
+	fmt.Println("  - Saves metadata including track status")
+	fmt.Println("  - Creates organized directory structure")
+	fmt.Println("")
+	fmt.Println("TROUBLESHOOTING:")
+	fmt.Println("  404 errors: Content may be region-locked, try different")
+	fmt.Println("              storefront in URL (e.g., /us/, /gb/, /jp/)")
+}
+
+// printConfigHelp prints help for the config command
+func printConfigHelp() {
+	fmt.Println("songlink-cli config - Configure Apple Music API credentials")
+	fmt.Println("")
+	fmt.Println("USAGE:")
+	fmt.Println("  songlink-cli config")
+	fmt.Println("")
+	fmt.Println("DESCRIPTION:")
+	fmt.Println("  Interactive setup wizard for Apple Music API credentials.")
+	fmt.Println("  Required for search, download, and playlist features.")
+	fmt.Println("")
+	fmt.Println("WHAT YOU'LL NEED:")
+	fmt.Println("  1. Apple Developer account")
+	fmt.Println("  2. MusicKit-enabled API key")
+	fmt.Println("  3. Team ID and Key ID")
+	fmt.Println("  4. Private key (.p8 file)")
+	fmt.Println("")
+	fmt.Println("SETUP STEPS:")
+	fmt.Println("  1. Sign in to https://developer.apple.com")
+	fmt.Println("  2. Go to Certificates, Identifiers & Profiles")
+	fmt.Println("  3. Under Keys, create a new key")
+	fmt.Println("  4. Enable MusicKit service")
+	fmt.Println("  5. Download the .p8 private key file")
+	fmt.Println("  6. Note your Team ID and Key ID")
+	fmt.Println("")
+	fmt.Println("STORED LOCATION:")
+	fmt.Println("  ~/.songlink-cli/config.json")
+	fmt.Println("")
+	fmt.Println("SECURITY:")
+	fmt.Println("  Credentials are stored locally and never transmitted")
+	fmt.Println("  except to Apple's API servers.")
 }
 
 func loadingIndicator(stop chan bool) {