ncmctl-dev

name: ncmctl-dev description: > 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.

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

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

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

Key Dependencies

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.