{"id":30318465,"url":"https://github.com/guitaripod/songlink-cli","last_synced_at":"2025-08-17T20:12:09.727Z","repository":{"id":58508112,"uuid":"531627965","full_name":"guitaripod/songlink-cli","owner":"guitaripod","description":"Convert music URLs \u0026 download tracks","archived":false,"fork":false,"pushed_at":"2025-07-18T20:26:15.000Z","size":1718,"stargazers_count":5,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-17T11:49:21.373Z","etag":null,"topics":["cli","go","linux","macos","music","windows"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guitaripod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-01T17:50:57.000Z","updated_at":"2025-07-18T20:26:19.000Z","dependencies_parsed_at":"2024-11-14T00:33:02.023Z","dependency_job_id":"de685830-1547-4b4a-8e77-8ebcbad77099","html_url":"https://github.com/guitaripod/songlink-cli","commit_stats":null,"previous_names":["guitaripod/songlink-cli"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/guitaripod/songlink-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitaripod%2Fsonglink-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitaripod%2Fsonglink-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitaripod%2Fsonglink-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitaripod%2Fsonglink-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guitaripod","download_url":"https://codeload.github.com/guitaripod/songlink-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitaripod%2Fsonglink-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270899582,"owners_count":24664720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","go","linux","macos","music","windows"],"created_at":"2025-08-17T20:12:09.196Z","updated_at":"2025-08-17T20:12:09.714Z","avatar_url":"https://github.com/guitaripod.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Songlink CLI\n\n[![Github All Releases](https://img.shields.io/github/downloads/guitaripod/songlink-cli/total.svg)](https://github.com/guitaripod/songlink-cli/releases)\n\nA Go program that retrieves Songlink and Spotify links for a given URL using the Songlink API. It also allows searching for songs and albums directly using Apple Music API. The output is designed to be shared as is, allowing the receiver to both use Songlink and listen to the song preview using Spotify's embed feature.\n\n## Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Process URL from clipboard](#process-url-from-clipboard)\n  - [Search for songs or albums](#search-for-songs-or-albums)\n  - [Download single tracks](#download-single-tracks)\n  - [Download playlists/albums](#download-entire-playlists-or-albums)\n- [Examples](#examples)\n- [Contributions](#contributions)\n- [License](#license)\n\n## Features\n\n-   Retrieves Songlink and Spotify links for a given song or album URL\n-   Search for songs and albums directly using Apple Music API\n-   Download full tracks as MP3 or MP4 files with album artwork\n-   Download entire playlists or albums from Apple Music URLs\n-   Supports command line arguments for customizing the output format\n-   Automatically copies the output to the clipboard for easy sharing\n-   Includes a loading indicator to provide visual feedback during the retrieval process\n-   Comprehensive built-in help system (`songlink-cli --help`)\n-   Thoroughly tested with unit tests to ensure reliability and correctness\n\n## Installation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📦 Installation Methods\u003c/strong\u003e\u003c/summary\u003e\n\n### macOS\n\n#### Homebrew\n\n```\nbrew tap guitaripod/songlink-cli\nbrew install songlink-cli\n```\n\n#### Build from Source\n\n1. Clone the repository: `git clone https://github.com/guitaripod/songlink-cli.git`\n2. Navigate to the project directory: `cd songlink-cli`\n3. Install dependencies: `go mod download`\n4. Build the executable: `go build -o songlink-cli .`\n5. Run the program: `./songlink-cli`\n\n### Download Pre-built Binaries\n\nGo to [Releases](https://github.com/guitaripod/songlink-cli/releases) and download the appropriate version for your operating system (Linux, macOS, Windows).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🛠️ Dependencies for Download Features\u003c/strong\u003e\u003c/summary\u003e\n\nTo use the download functionality (single tracks or playlists), you need:\n\n- `yt-dlp` - For downloading audio from YouTube\n- `ffmpeg` - For audio/video processing\n\n**Install on macOS:**\n```bash\nbrew install yt-dlp ffmpeg\n```\n\n**Install on Linux:**\n```bash\n# Ubuntu/Debian\nsudo apt install yt-dlp ffmpeg\n\n# Arch\nsudo pacman -S yt-dlp ffmpeg\n```\n\n\u003c/details\u003e\n\n## Usage\n\n```\nsonglink-cli [flags]                    Process URL from clipboard\nsonglink-cli \u003ccommand\u003e [flags] \u003cargs\u003e   Run a specific command  \nsonglink-cli help \u003ccommand\u003e             Show help for a command\n```\n\nRun `songlink-cli --help` for comprehensive documentation of all features.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📋 Process URL from Clipboard\u003c/strong\u003e\u003c/summary\u003e\n\n1. Copy the URL of the song or album you want to retrieve links for.\n2. Run the program using one of the following commands:\n    - `songlink-cli`: Retrieves only the Songlink URL\n    - `songlink-cli -x`: Retrieves the Songlink URL without surrounding `\u003c\u003e` (for Twitter)\n    - `songlink-cli -d`: Retrieves the Songlink URL surrounded by `\u003c\u003e` and the Spotify URL (for Discord)\n    - `songlink-cli -s`: Retrieves only the Spotify URL\n3. The program will automatically retrieve the Songlink and/or Spotify link for the song or album and copy it to your clipboard.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔍 Search for Songs or Albums\u003c/strong\u003e\u003c/summary\u003e\n\n### Basic Search\n\n1. Configure your Apple Music API credentials (first time only):\n   ```bash\n   songlink-cli config\n   ```\n   \n2. Search for a song or album:\n   ```bash\n   songlink-cli search \"song or album name\"\n   ```\n   \n3. Select from the search results by entering the number.\n\n4. After selecting a result, you will be prompted to choose an action:\n   - **Option 1**: Copy the song.link + Spotify URL to clipboard  \n   - **Option 2**: Download the full track as MP3  \n   - **Option 3**: Download a video (MP4) with the album artwork\n\n5. If you choose to download, the file(s) will be saved in the `downloads/` directory by default.\n\n### Advanced Search Examples\n\n```bash\n# Search for a specific song\nsonglink-cli search \"Bohemian Rhapsody\"\n\n# Search for albums only\nsonglink-cli search -type=album \"Abbey Road\"\n\n# Search and format for Discord sharing\nsonglink-cli search -d \"Hotel California\"\n\n# Search with custom download directory\nsonglink-cli search -out=~/Music \"Imagine\"\n```\n\n### Search Flags\n\n- `-type=song`: Search for songs only (default)\n- `-type=album`: Search for albums only\n- `-type=both`: Search for both songs and albums\n\nCombined with output format flags:\n```\n./songlink search -type=album -d \"Dark Side of the Moon\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e💿 Download Single Tracks\u003c/strong\u003e\u003c/summary\u003e\n\nDownload individual tracks as audio files or videos with artwork.\n\n```bash\n./songlink download [flags] \u003cquery\u003e\n```\n\n### Flags\n\n| Flag | Options | Default | Description |\n|------|---------|---------|-------------|\n| `-type` | `song`, `album` | `song` | Type of Apple Music search |\n| `-format` | `mp3`, `mp4` | `mp3` | Download format (MP3 audio or MP4 video with artwork) |\n| `-out` | Directory path | `downloads` | Output directory for downloaded files |\n| `-debug` | - | `false` | Show yt-dlp and ffmpeg output |\n\n### Examples\n\n```bash\n# Download a song as MP3 (default)\nsonglink-cli download \"Stairway to Heaven\"\n\n# Download as MP4 with album artwork\nsonglink-cli download -format=mp4 \"Purple Rain\"\n\n# Download to custom directory\nsonglink-cli download -out=~/Music \"Yesterday\"\n\n# Download with debug output\nsonglink-cli download -debug \"Wonderwall\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📀 Download Entire Playlists or Albums\u003c/strong\u003e\u003c/summary\u003e\n\nDownload all tracks from an Apple Music playlist or album URL.\n\n```bash\n./songlink playlist [flags] \u003capple-music-url\u003e\n```\n\n### ⚠️ Supported Content\n\n**✅ Supported:**\n- Public catalog albums (e.g., `https://music.apple.com/us/album/album-name/123456789`)\n- Public catalog playlists (e.g., `https://music.apple.com/us/playlist/playlist-name/pl.abcdef123456`)\n\n**❌ Not Supported:**\n- Personal library playlists (`/library/playlist/`)\n- Private or user-created playlists\n- Region-locked content (may return 404 errors)\n- Apple Music Radio stations\n\n### Flags\n\n| Flag | Options | Default | Description |\n|------|---------|---------|-------------|\n| `--format` | `mp3`, `mp4` | `mp3` | Download format for all tracks |\n| `--out` | Directory path | `downloads` | Output directory for downloaded files |\n| `--concurrent` | `1-10` | `3` | Number of parallel downloads |\n| `--metadata` | - | `false` | Save playlist/album metadata as JSON |\n| `--debug` | - | `false` | Show detailed download progress and debug info |\n\n### Examples\n\n```bash\n# Download an album\n./songlink playlist \"https://music.apple.com/us/album/abbey-road/401469823\"\n\n# Download a playlist with metadata\n./songlink playlist --metadata \"https://music.apple.com/us/playlist/top-100-global/pl.d25f5d1181894928af76c85c967f8f31\"\n\n# Download with custom settings\n./songlink playlist --format=mp4 --out=my-music --concurrent=5 \"https://music.apple.com/album/...\"\n```\n\n### Features\n\n- **Parallel Downloads**: Downloads multiple tracks simultaneously for faster completion\n- **Automatic Retry**: Failed downloads are retried with exponential backoff\n- **Progress Tracking**: Real-time progress for each track\n- **Metadata Support**: Saves playlist/album info and track details as JSON\n- **Smart Directory Creation**: Automatically creates output directories\n\n### Troubleshooting\n\n#### 404 Resource Not Found Errors\n- The playlist/album may be region-locked\n- The content may have been removed  \n- Try using a different storefront in the URL (e.g., `/us/`, `/gb/`, `/jp/`)\n\n#### Download Failures\n- Ensure `yt-dlp` and `ffmpeg` are installed and up to date\n- Some tracks may not be available on YouTube\n- Try reducing `--concurrent` value if experiencing rate limits\n- Use `--debug` flag to see detailed error messages\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔐 Apple Music API Setup\u003c/strong\u003e\u003c/summary\u003e\n\nTo use the search and download functionality, you need Apple Music API credentials. The CLI includes a guided setup process:\n\n1. Run `./songlink config`\n2. Follow the prompts to enter your Apple Developer credentials:\n   - Team ID\n   - Key ID\n   - Private Key (from your .p8 file)\n   - Music ID (usually the same as Team ID)\n\nYour credentials will be securely stored in `~/.songlink-cli/config.json`\n\n### Getting Apple Music API Credentials\n\n1. Sign in to [Apple Developer](https://developer.apple.com)\n2. Go to Certificates, Identifiers \u0026 Profiles\n3. Under Keys, create a new key with MusicKit enabled\n4. Download the .p8 private key file\n5. Note your Team ID and Key ID\n\n\u003c/details\u003e\n\n## Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📚 Quick Examples\u003c/strong\u003e\u003c/summary\u003e\n\n### Link Retrieval from Clipboard\n\n```bash\n# Get Songlink URL (default)\nsonglink-cli\n\n# Get Songlink URL without \u003c\u003e for Twitter\nsonglink-cli -x\n\n# Get Songlink URL with \u003c\u003e + Spotify URL for Discord\nsonglink-cli -d\n\n# Get only Spotify URL\nsonglink-cli -s\n```\n\n### Search Examples\n\n```bash\n# Search for a song\nsonglink-cli search \"Bohemian Rhapsody\"\n\n# Search for an album with Discord format\nsonglink-cli search -type=album -d \"Abbey Road\"\n\n# Search for both songs and albums\nsonglink-cli search -type=both \"Beatles\"\n\n# Search with custom download directory\nsonglink-cli search -out=~/Downloads \"Imagine\"\n```\n\n### Download Examples\n\n```bash\n# Download a single track as MP3\nsonglink-cli download \"Purple Rain\"\n\n# Download a single track as MP4 with artwork\nsonglink-cli download -format=mp4 \"Imagine\"\n\n# Download to specific directory with debug output\nsonglink-cli download -out=~/Music -debug \"Let It Be\"\n```\n\n### Playlist/Album Download Examples\n\n```bash\n# Download an entire album\nsonglink-cli playlist \"https://music.apple.com/us/album/abbey-road/401469823\"\n\n# Download playlist with metadata\nsonglink-cli playlist --metadata \"https://music.apple.com/us/playlist/top-100-global/pl.d25f5d1181894928af76c85c967f8f31\"\n\n# Fast download with 5 workers and MP4 format\nsonglink-cli playlist --concurrent=5 --format=mp4 \"https://music.apple.com/album/...\"\n\n# Download with all options\nsonglink-cli playlist --format=mp4 --out=my-music --concurrent=5 --metadata --debug \"https://music.apple.com/playlist/...\"\n```\n\n\u003c/details\u003e\n\n## Contributions\n\nI welcome contributions to the Songlink CLI project! If you have any ideas, suggestions, or bug reports, please don't hesitate to open an issue or submit a pull request. To contribute:\n\n1. Fork the repository\n2. Create a new branch for your feature or bug fix\n3. Make your changes and commit them with descriptive commit messages\n4. Push your changes to your forked repository\n5. Submit a pull request to the main repository\n\nI appreciate your help in making this project better!\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\nI hope you find this tool useful! If you have any questions or need further assistance, please let me know.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguitaripod%2Fsonglink-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguitaripod%2Fsonglink-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguitaripod%2Fsonglink-cli/lists"}