OpenParable
Skip to content
← Back to skills

Ncmctl

Apps & Automation
ncmctl

Ncmctl is an Agent Skill for apps & automation published in the chaunsin/netease-cloud-music repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/chaunsin/netease-cloud-music/blob/HEAD/skills/ncmctl/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ncmctl, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

CommandLoginDescription
loginNoPhone/Cookie/CookieCloud/QR code login
logoutNoClear stored credentials
taskYesRun daily tasks on cron schedule
signYesYunBei + VIP daily check-in
partnerYesMusic partner auto-evaluation
scrobbleYesScrobble songs daily (default 300, max 300)
downloadYesDownload songs/albums/playlists
cloudYesUpload music to cloud disk
ncmNoDecrypt .ncm to .mp3/.flac
cryptoNoEncrypt/decrypt API parameters (debugging only)
curlNoInvoke API methods directly (ncmctl subcommand, not system curl)

Global Flags

FlagDefaultDescription
--debugfalseEnable debug mode
-c, --confignoneConfig file path
--home~/.ncmctlHome directory for runtime data

Configuration Paths

ItemDefault Path
Config~/.ncmctl/config.yaml
Cookie~/.ncmctl/cookie.json
Database~/.ncmctl/database/badger/
Logs~/.ncmctl/log/ncm.log

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

FileContentWhen to read
references/install-and-login.mdInstallation methods and login proceduresSetting up ncmctl for the first time or troubleshooting login issues
references/commands.mdAll command flags, parameters, and examplesLooking up detailed command syntax, flags, or execution flow