version: "1.0.1" name: ncmctl description: >- Install, configure, operate, and troubleshoot the ncmctl command-line client for NetEase Cloud Music. Use this skill when the user mentions ncmctl or asks for CLI-based NetEase login, Cookie or CookieCloud import, QR/SMS login, scheduled sign/partner/scrobble tasks, song download, cloud-disk upload, NCM-to-MP3/FLAC decryption, API crypto/curl debugging, Docker deployment, or the local HTTP(S) capture proxy. Also use it for ncmctl flags, shell completion, config files, runtime paths, credentials, and proxy CA safety. Do not trigger for general music recommendations, official app usage, or repository development; the repository-local ncmctl-dev skill covers source changes.

ncmctl User Guide

ncmctl is a Go CLI for NetEase Cloud Music login, scheduled account tasks, media download/upload, NCM decryption, API debugging, and local HTTP(S) traffic monitoring.

How to use this skill

1. Identify whether the user needs installation/login help or a command reference.
2. Start with the matching reference file listed at the end. Load the other only when the request crosses installation/login and command/config concerns.
3. Prefer the installed binary's ncmctl <command> --help output when available; it is the exact syntax for that version.
4. Explain network, credential, filesystem, and account effects before suggesting a command that causes them.
5. Never invent flags, interactive prompts, environment variables, exit codes, or decryption capabilities that are not documented here or shown by the binary.

Do not perform an action that changes an account or credentials, writes or deletes files, modifies a trust store, starts a listener, or launches a long-running service unless the user explicitly requested that effect. Representative commands include login/logout, account tasks, media operations, curl, and proxy.

Installation check

ncmctl --version
ncmctl --help

If the command is missing, read references/install-and-login.md. Source installation requires Go 1.25.0 or newer:

go install github.com/chaunsin/netease-cloud-music/cmd/ncmctl@latest

Prebuilt binaries are published on the project's GitHub Releases page.

Command map

Read references/commands.md for flags, limits, side effects, and examples.

Global flags and runtime data

Without --config, ncmctl uses its embedded defaults; it does not automatically load ~/.ncmctl/config.yaml.

Default runtime paths under <home>:

For custom configuration, copy the full schema from config/config.yaml, edit it, and pass the path explicitly with --config.

Safety boundaries

• Account risk: scrobble, partner evaluation, automatic reward claims, and other automation can trigger NetEase risk control. Scrobble has a particularly high ban risk.
• Credentials: Cookie values, MUSIC_U, phone passwords, CookieCloud UUID/passwords, and XEAPI dynamic/session keys are secrets. Phone-password, CookieCloud, and XEAPI key inputs are flags; they do not provide a hidden prompt or dedicated environment variable. In particular, proxy --xeapi-session-key is visible in shell history and process arguments.
• TLS verification: The current NetEase API and CookieCloud clients disable server-certificate verification. HTTPS traffic is encrypted but the peer identity is not authenticated; use only a trusted network path and CookieCloud server.
• State files: Cookies, XEAPI session state, and anonymous tokens are sensitive. ncmctl creates its managed state files with restrictive permissions on POSIX, but backups, exported Cookies, and user-provided header.yaml files remain the user's responsibility. Prefer login cookie -f over placing a Cookie string directly in shell history.
• Cookie import persistence: Cookie and CookieCloud imports enter the configured persistent jar before account validation. A failed validation can still write those values during immediate, periodic, or final flush.
• Proxy CA: Trust only ca.crt on a client you control. Never install, share, or commit ca.key. Remove trust when monitoring is finished if it is no longer needed.
• Sensitive capture: Proxy redaction is enabled by default. --show-sensitive can expose credentials and identifiers in the terminal or redirected files.
• Debug logs: Global --debug enables raw API request/response logging outside the proxy redactor. Treat stderr, rolling logs, and redirected output as sensitive.
• LAN proxy: --listen 0.0.0.0:9000 is unauthenticated. Use it only temporarily on a trusted network behind a firewall.
• Local files: Download, upload, NCM decode, QR login, HAR processing, and redirected proxy output read or write local files. Confirm paths before running them.

Common workflows

Schedule sign and scrobble

ncmctl task --sign --scrobble

task is a long-running service. With no selectors it registers sign, partner, and scrobble; explicit selectors limit the jobs. Press Ctrl+C or send SIGTERM to stop it.

Download a playlist

ncmctl download -l lossless \
  'https://music.163.com/playlist?id=593617579' \
  -o ./music

Decode local NCM files

ncmctl ncm '/path/to/ncm/files' -o ./decoded -p 10

The historical ncm --tag flag is inverted: tags are written by default, and passing --tag disables tag writing.

Monitor local API traffic

ncmctl proxy
ncmctl proxy > capture.log
ncmctl proxy --xeapi-state-file ~/.ncmctl/xeapi.yaml

Configure the client to use 127.0.0.1:9000 for HTTP and HTTPS, then trust <home>/.ncmctl/proxy/ca.crt. The proxy never modifies the system trust store automatically.

XEAPI session state is opt-in at startup: proxy does not discover <home>/.ncmctl/xeapi.yaml unless --xeapi-state-file names it. It can also accept a paired --xeapi-session-id / --xeapi-session-key; the ID is at most 1024 bytes and the key is raw ASCII of 16, 24, or 32 bytes. During capture, valid session response headers are learned in memory for later requests and are not written back. Requests without a matching key remain partial; S is only structurally validated because the proxy has neither side's X25519 private key.

Use ncmctl --debug proxy to correlate the CONNECT target with ClientHello SNI, the selected tunnel/MITM action, generated certificate SANs, and hostname-match results. An IP-targeted CONNECT is MITM'd only when its exposed SNI matches a configured NetEase domain and remains pinned to the original IP upstream. CONNECT diagnostics describe the underlying tunnel, not every HTTP request carried by it, so a reused tunnel produces no new phase=connect record. Investigate QUIC/HTTP3, direct connections, or another bypass path only after confirming that the underlying connection also had no CONNECT record when it was established.

References