OpenParable
Skip to content
← Back to skills

Ncmctl Dev

Apps & Automation
ncmctl-dev

Ncmctl Dev 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.

NetEase Cloud Music CLI tool (ncmctl) development guide. Use this skill when working with the netease-cloud-music codebase, including ncmctl commands, API integration, crypto, NCM file decryption, daily tasks, music download, cloud upload, or any Go code in this repository. Trigger on mentions of ncmctl, 网易云音乐 CLI, NetEase Cloud Music API, weapi/eapi encryption, .ncm file format, cloud music daily tasks (sign/partner/scrobble), or when modifying, debugging, or extending any part of this project.

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/.claude/skills/ncmctl-dev/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ncmctl-dev, 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 Development Guide

ncmctl is a Go CLI tool for NetEase Cloud Music providing login, daily tasks, music download, cloud upload, and NCM file decryption.

Project Structure

cmd/ncmctl/main.go       # CLI entry point
internal/ncmctl/          # CLI command implementations (cobra commands)
api/                      # API client layer
  ├── api.go              # Core Client: HTTP, encryption, cookie persistence
  ├── weapi/              # Web/Mini-program API (recommended, most complete)
  ├── eapi/               # PC/Mobile API
  ├── linux/              # Linux client API
  └── types/              # Shared request/response types
pkg/
  ├── crypto/             # AES-CBC/ECB, RSA, weapi/eapi encryption
  ├── cookie/             # Cookie persistence and sync
  ├── cookiecloud/        # CookieCloud browser extension support
  ├── ncm/                # NCM file decryption + audio tag handling
  ├── database/           # Badger key-value store wrapper
  ├── log/                # Structured logging (lumberjack rotation)
  └── utils/              # General utilities
config/                   # Config structs + default config.yaml

Build & Test

make build                # Build binary → ./ncmctl
make install              # Install to $GOPATH/bin
go test -v ./...          # Run all tests
go test -v -run TestName ./example/  # Run single test
make build-image          # Build Docker image

Requires Go >= 1.24. Tests needing login require cookie file or should be skipped.

CLI Commands

CommandLoginDescription
loginNoPhone/Cookie/CookieCloud/QR code login
logoutNoClear stored credentials
taskYesRun all daily tasks on cron schedule
signYesYunBei + VIP daily check-in
partnerYesMusic partner auto-evaluation
scrobbleYesScrobble 300 songs daily
downloadYesDownload songs/albums/playlists
cloudYesUpload music to cloud disk
ncmNoDecrypt .ncm → .mp3/.flac
cryptoNoEncrypt/decrypt API parameters
curlNoInvoke API methods directly

Adding a New CLI Command

  1. Create internal/ncmctl/<command>.go implementing a struct with root, cmd, opts, l fields
  2. Implement New<Command>(root *Root, l *log.Logger) constructor
  3. Define cobra command with Use, Short, Example
  4. Add flags via addFlags() method
  5. Implement validate() and execute(ctx, args) methods
  6. For login-required commands: create API client, check request.NeedLogin(ctx), defer request.TokenRefresh(ctx, &weapi.TokenRefreshReq{})
  7. Register in internal/ncmctl/ncmctl.go: c.Add(New<Command>(c, c.l).Command())

Pattern for login-required commands:

cli, err := api.NewClient(c.root.Cfg.Network, c.l)
if err != nil { return fmt.Errorf("NewClient: %w", err) }
defer cli.Close(ctx)
request := weapi.New(cli)
if request.NeedLogin(ctx) { return fmt.Errorf("need login") }
defer func() {
    refresh, err := request.TokenRefresh(ctx, &weapi.TokenRefreshReq{})
    if err != nil || refresh.Code != 200 {
        log.Warn("TokenRefresh resp:%+v err: %s", refresh, err)
    }
}()

Adding a New API Endpoint

  1. Create file in api/weapi/ or api/eapi/
  2. Define request/response structs (request fields use json tags)
  3. Implement method on API struct calling a.client.Request(ctx, url, req, resp, opts...)
  4. Set correct CryptoMode via option: api.WithCryptoMode(api.CryptoModeWEAPI)
  5. Default crypto mode is weapi; eapi uses CryptoModeEAPI

API call flow:

cli := api.New(cfg)
weapiClient := weapi.New(cli)
resp, err := weapiClient.SomeMethod(ctx, &weapi.SomeMethodReq{...})
cli.Close(ctx)

Encryption Modes

ModeAlgorithmUse Case
CryptoModeWEAPIAES-CBC double encrypt + RSAWeb/Mini-program
CryptoModeEAPIAES-ECBPC/Mobile
CryptoModeLinuxAES-ECBLinux client
CryptoModeAPINoneBasic API

Core functions in pkg/crypto/crypto.go: WeApiEncrypt(), EApiEncrypt(), LinuxApiEncrypt(), EApiDecrypt().

Configuration

  • Config file: ~/.ncmctl/config.yaml (optional, uses defaults if absent)
  • Cookie storage: ~/.ncmctl/cookie.json (auto-persisted, 3s interval)
  • Database: ~/.ncmctl/database/badger/ (scrobble dedup records)
  • Logs: ~/.ncmctl/log/ncm.log
  • Env var prefix: NCmctl_ (e.g., NCmctl_Network_Debug=true)
  • Magic variable: ${HOME} replaced at runtime

Download Quality Levels

LevelAliasesFormat
standard128128kbps
higher192192kbps
exhighHQ, 320320kbps
losslessSQFLAC
hiresHRHi-Res

Key Dependencies

PackagePurpose
spf13/cobraCLI framework
go-resty/resty/v2HTTP client
dgraph-io/badger/v4Local KV database
robfig/cron/v3Cron scheduling
spf13/viperConfig management

Important Notes

  • Cookie persistence is interval-based (3s); unclean shutdown may lose recent cookies
  • Scrobble dedup data in ~/.ncmctl/database/ should not be deleted
  • Directory depth limit is 3 for cloud upload and NCM decryption
  • Cloud upload max file size: 500MB
  • Download parallelism max: 20; Cloud upload parallelism max: 10
  • The task command runs as a long-lived service; use Ctrl+C to stop
  • Sign-in reward auto-claim (--sign.automatic) has ban risk, disabled by default
  • Scrobble (刷歌) currently has high risk of account ban due to strict risk control

For detailed command usage and API reference, read references/commands.md and references/api-guide.md.