ncm-cli-setup

ncm-cli Installation and Configuration

ncm-cli is the CLI tool for NetEase Cloud Music (music search, playback control, playlist management, TUI player).

Installation Process

npm install -g @music163/ncm-cli

Verify installation:

ncm-cli --version

The playback feature requires the mpv player. First check whether it is already installed:

mpv --version

macOS / Windows: If not installed, run the installation script directly:

python3 scripts/install_mpv.py

Linux: Ask the user whether the playback feature is needed:

If it is a desktop environment and local playback is needed → run python3 scripts/install_mpv.py
If it is a server environment and playback is not needed → skip; commands such as search/playlist still work normally

The installation script automatically detects the package manager:

To use ncm-cli, you need to set the API Key first:

ncm-cli config set appId <你的AppId>
ncm-cli config set privateKey <你的PrivateKey>

If you do not have an API Key yet, please first go toNetEase Cloud Music Open Platformto apply for an API Key (appId and privateKey).

Ask the user to choose the default player:

mpv(built-in player): lightweight, cross-platform, requires completing the mpv installation in Step 1 first
orpheus(Cloud Music App): calls the local NetEase Cloud Music client for playback, only supported on macOS

Execute according to the user's choice:

ncm-cli config set player mpv      # 选择内置播放器
ncm-cli config set player orpheus  # 选择云音乐 App

Logging in is required, please use:

ncm-cli login --background

Issue	Solution
`ncm-cli: command not found`	Check whether the npm global bin is in PATH:`npm bin -g`
`mpv not found`	Re-run `python3 scripts/install_mpv.py` or install manually:https://mpv.io
Login timeout	Re-execute `ncm-cli login --background`