npm package: @sbdh11/musicfetch
Description: CLI to search Spotify for tracks and albums from the terminal.
Author: Subodh Inamdar
Latest version: 0.1.1

# musicfetch

A cross-platform CLI to search Spotify for tracks and albums from your terminal with clean text or rich grid outputs.

- Built with Node.js and Commander
- Uses Spotify Web API (Client Credentials flow)
- Pretty output with optional album art rendering via Sharp

## How it works
- Authentication uses Spotify Client Credentials. You provide `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` in a `.env` file.
- The CLI calls Spotify endpoints and renders results:
  - `track <query>`: search tracks (filter by artist, list or grid output)
  - `album <query>`: search albums (list or grid output). Album results are enriched with full album details, genres, and total duration.

## Requirements
- Node.js >= 18
- A Spotify Developer application (for Client ID and Client Secret)
- Internet access

Notes about Sharp (image processing): prebuilt binaries are used for most platforms. If Sharp falls back to building from source (rare), you may need build tools.

## Installation
Install locally (project dependency) or globally.

### Option A: Install locally (recommended in a project)
```bash
npm i @sbdh11/musicfetch
```

### Option B: Global install
```bash
npm install -g @sbdh11/musicfetch
```

After installing globally, the command is:
```bash
musicfetch --help
```

## OS-specific setup

### Linux
- Ensure Node.js >= 18 is installed (`node -v`).
- If Sharp needs to build from source, install build tools:
  - Debian/Ubuntu: `sudo apt-get update && sudo apt-get install -y build-essential python3 make gcc g++`
  - Fedora/RHEL: `sudo dnf groupinstall -y "Development Tools"` and `sudo dnf install -y python3 make gcc-c++`

### macOS
- Install Node.js >= 18 (Homebrew recommended): `brew install node`
- If Sharp build is required (rare): `xcode-select --install`

### Windows
- Install Node.js >= 18 from `https://nodejs.org/`
- If Sharp build is required (rare):
  - Install Visual Studio Build Tools (C++ workload)
  - Ensure Python 3 is available (`py --version` or `python --version`)

## Configuration
Create a `.env` file in the project root (or your working directory when running the CLI) with your Spotify credentials:

```env
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
```

To obtain these values:
- Go to the Spotify Developer Dashboard and create an app.
- Copy the Client ID and Client Secret into your `.env`.

The CLI uses the Client Credentials flow only; it does not access user private data.

## Usage
You can run via global command or with `node` directly from the repo:

```bash
musicfetch --help
node ./bin/spotify.js --help
```

### Commands

- Track search
  ```bash
  musicfetch track <query> [options]
  ```
  Options:
  - `-l, --limit <n>`: results limit (default: 5)
  - `-a, --artist <name>`: filter results to a specific artist
  - `-g, --grid`: display results in a rich grid format

- Album search
  ```bash
  musicfetch album <query> [options]
  ```
  Options:
  - `-l, --limit <n>`: results limit (default: 5)
  - `-g, --grid`: display results in a rich grid format

### Examples
```bash
# Find tracks named "yellow"
musicfetch track "yellow"

# Find tracks named "yellow" by Coldplay, show 10 results
musicfetch track "yellow" --artist Coldplay --limit 10

# Show results as a grid with artwork
musicfetch track "yellow" --grid

# Search albums and show as simple list
musicfetch album "random access memories"

# Search albums and show as grid
musicfetch album "random access memories" --grid
```

## Troubleshooting
- "Spotify API 401/400" errors: verify your `.env` has correct `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` and that they load in your shell directory.
- Sharp install errors: install platform build tools (see OS-specific setup) or try clearing npm cache and reinstalling: `npm rebuild sharp`.
- Network errors: check proxy/VPN and retry.

## Uninstall
```bash
npm uninstall -g @sbdh11/musicfetch
```

## License
MIT