ncmctl

name: ncmctl description: >- ncmctl CLI reference and usage guide for NetEase Cloud Music. Use this skill when the user mentions ncmctl, 网易云音乐命令行, 网易云音乐, 网易云, 网易音乐, NetEase Cloud Music CLI, or asks how to install, login, download songs, upload to cloud, decrypt NCM files, convert ncm to mp3/flac, run daily tasks (sign/partner/scrobble), 刷歌, 云贝签到, 音乐合伙人, 黑胶签到, or use API debugging tools. Also trigger on questions about ncmctl configuration, cookie management, or Docker deployment. Use even if the user does not explicitly say "ncmctl" when the work is clearly related to NetEase Cloud Music CLI operations. metadata: author: chaunsin version: "0.1.0"

ncmctl - NetEase Cloud Music CLI

ncmctl is a Go CLI for NetEase Cloud Music: login, daily tasks, music download, cloud upload, NCM decryption, and API debugging.

Prerequisites

# Check if ncmctl is installed
ncmctl --version

# Install options:

# Go install (requires Go >= 1.25.0)
go install github.com/chaunsin/netease-cloud-music/cmd/ncmctl@latest

# Or download pre-built binary from GitHub Releases
# https://github.com/chaunsin/netease-cloud-music/releases

Quick Reference

Global Flags

Configuration Paths

Env var prefix: NCmctl_ (e.g., NCmctl_Log_Level=debug). Note: the mixed-case prefix NCmctl_ is the actual prefix used by the tool.

Security Considerations

IMPORTANT: ncmctl handles authentication credentials and performs actions on your NetEase Cloud Music account. Pay close attention to the following safety guidelines:

• Never pass passwords on the command line — they are visible in shell history and process listings. Prefer interactive prompts or environment variables.
• Protect cookie files — ~/.ncmctl/cookie.json contains sensitive session credentials. Set file permissions immediately after login:

  chmod 600 ~/.ncmctl/cookie.json
  

• Be cautious with CookieCloud credentials — the UUID and password for CookieCloud login are sensitive; avoid sharing or logging them. Use environment variables or interactive prompts instead of command-line arguments.
• Docker volume mounts — when running in Docker, the mounted volume (-v ./data:/root) may expose credentials on the host filesystem. Ensure the host directory has restricted permissions:

  chmod 700 ./data
  

• Account ban risks — automated tasks (scrobble, sign automatic rewards, partner evaluation) may trigger NetEase risk control and result in account restrictions. Use at your own risk.

Important Warnings

• Scrobble (刷歌) has high ban risk due to strict risk control
• --sign.automatic auto-claim rewards has ban risk, disabled by default
• Cookie persistence is interval-based (3s); unclean shutdown may lose recent cookies
• Do not delete ~/.ncmctl/database/ (scrobble dedup data)
• Directory depth limit: 3 for cloud upload and NCM decryption
• Cloud upload max file size: 500MB

Common Workflows

Daily Automation (Sign + Scrobble)

# Run as a background service with cron scheduling
ncmctl task --sign --scrobble

# Or run commands individually
ncmctl sign
ncmctl scrobble -n 200

Batch Download Playlist and Decrypt NCM

# Download a playlist
ncmctl download 'https://music.163.com/playlist?id=593617579' -o ./music/

# Decrypt downloaded NCM files
ncmctl ncm ./music/ -o ./decrypted/ -p 10

Docker Scheduled Tasks

# Run daily tasks in Docker container
docker run -d -v ./data:/root \
  --name ncmctl-daily \
  --restart unless-stopped \
  chaunsin/ncmctl:latest \
  /app/ncmctl task --sign --scrobble

Reference Files