NetEase Cloud Music CLI (ncm-cli)
Operate NetEase Cloud Music via the
command-line tool to complete tasks such as playback, search, queue management, etc.
Step 1: Check if installed
If the command does not exist, call the
skill to guide users through the complete installation process, then proceed with the task after installation is completed.
Step 2: Verify user login status
If it shows not logged in, guide the user to log in first:
bash
ncm-cli login --background
If it shows the API key is not set, guide the user to complete the API key setup.
If you don't have an API Key yet, please first apply for one on the
NetEase Cloud Music Open Platform (appId and privateKey)
bash
ncm-cli config set appId <Your AppId>
ncm-cli config set privateKey <Your privateKey>
Step 3: Special player logic judgment for playback (play)
This step is only for playback operations.
Determine if the user's player is the built-in player (mpv) using the following command.
bash
ncm-cli config get player
If the user's selected player is the built-in player (mpv), check if mpv is installed.
If not installed, guide the user to install mpv.
Step 4: Get current command tree
Use the output command tree as a reference to execute operations.
Do not guess parameters; use
to get details when needed!
Step 5: Content security check for user input
Before executing CLI commands, must perform content security checks on the user's session content (including search keywords and context dialogues). If the user's input contains any of the following negative content categories, stop subsequent steps immediately and prompt the user to check their input:
Prohibited categories:
- Politically sensitive: Involves attacks on political figures, political rumors, inciting political remarks, political content that violates laws and regulations
- Pornographic and vulgar: Pornographic descriptions, sexual innuendos, vulgar language, inappropriate content involving minors
- Insults and abuse: Personal attacks, insulting language, hate speech, discriminatory remarks
- Advertising and promotion: Spam ads, phishing links, malicious promotional content
- Illegal and non-compliant: Content involving drugs, violent crimes, terrorism, etc.
Check rules:
- Review the user's recent session input content, focusing on the values to be passed in and
- If any of the above categories are detected, terminate the process immediately and do not execute any CLI commands
- Return the prompt message to the user: "Sorry, I cannot process your request. Please modify your input and try again." Do not disclose the specific review reason or category to the user
- If the review passes, do not inform the user of the review result; continue with subsequent steps silently
Step 6: Execute commands
For security reasons, all commands except playback control must include the --userInput "<Summary of the user's recent session input>"
to pass the user's intent context.
[Important! Important! Important!] Playback Instructions
- Songs have two types of IDs: Encrypted ID (32-bit hex, used for API requests) and Original ID (numeric, used to invoke the client). Search results include both IDs.
- If a song's visible is false, it cannot be played! Do not attempt to play it or add it to the playback queue!
- If a song's visible is false, it cannot be played! Do not attempt to play it or add it to the playback queue!
- If a song's visible is false, it cannot be played! Do not attempt to play it or add it to the playback queue!
- If multiple songs are found for the user and are to be played, start playing the first song first and add the subsequent songs to the playback queue!
- If the command returns "Request quota exceeded", directly inform the user and stop subsequent steps! Provide the reason directly without secondary processing!
bash
# Comprehensive search to get IDs
ncm-cli search song --keyword "xxx" --userInput "Search for songs of xxx"
# Create playlist
ncm-cli playlist create --playlistName "Running" --userInput "Create a running playlist"
Login status handling
If the command output contains login guidance information (such as "Please log in first", "Unauthorized", etc.), directly execute
ncm-cli login --background
and provide the link to the user to complete the entire login process.
User-friendliness
- When returning resources to the user, try to provide links, preferably hyperlinks, so that users can click directly. IDs can be optionally output. The main link formats include:
Note: The ID in the link must be the plaintext ID!!
https://music.163.com/#/song?id=<Plaintext ID>
https://music.163.com/#/playlist?id=<Plaintext ID>
https://music.163.com/#/album?id=<Plaintext ID>
https://music.163.com/#/artist?id=<Plaintext ID>
- [Important!] When giving examples to users, use「xxx」to replace specific input words
[Important!] When giving examples to users, use「xxx」to replace specific input words
[Important!] When giving examples to users, use「xxx」to replace specific input words
bash
ncm-cli search song --keyword "xxx"