ncm-cli Installation and Configuration
ncm-cli is a CLI tool for NetEase Cloud Music (supports music search, playback control, playlist management, and TUI player).
Installation Process
Step 1: Install ncm-cli and mpv
1.1 Install ncm-cli
bash
npm install -g @music163/ncm-cli
Verify installation:
1.2 Install mpv
Playback functionality requires the mpv player. First check if it is already installed:
macOS / Windows: If not installed, run the installation script directly:
bash
python3 scripts/install_mpv.py
Linux: Ask the user if playback functionality is needed:
- If it's a desktop environment and local playback is required → run
python3 scripts/install_mpv.py
- If it's a server environment and playback is not needed → skip, commands like search/playlist can still be used normally
The installation script will automatically identify the package manager:
- macOS: Homebrew () or MacPorts
- Linux: apt / dnf / pacman / zypper
- Windows: winget / Chocolatey / Scoop
Step 2: Configure API Key
Using ncm-cli requires setting the API Key first:
bash
ncm-cli config set appId <your AppId>
ncm-cli config set privateKey <your PrivateKey>
If you don't have an API Key yet, please go to
NetEase Cloud Music Open Platform to apply for an API Key (appId and privateKey).
Step 3: Configure Default Player
Ask the user to select the default player:
- mpv (built-in player): Lightweight, cross-platform, requires completing mpv installation in Step 1 first
- orpheus (Cloud Music App): Calls the local NetEase Cloud Music client for playback, only supports macOS
Execute according to the user's selection:
bash
ncm-cli config set player mpv # Select built-in player
ncm-cli config set player orpheus # Select Cloud Music App
Step 4: Login
Login is required, please use:
bash
ncm-cli login --background
Common Issues
| Issue | Solution |
|---|
ncm-cli: command not found
| Check if the npm global bin directory is in PATH: |
| Re-run python3 scripts/install_mpv.py
|
| Login timeout | Re-run ncm-cli login --background
|
Basic Information