An unofficial command-line client for The MLC Public Search API. Written in Rust. Binary: mlc.
Search musical works and recordings, look up songwriters and publishers, and retrieve works in batches. All four data endpoints in the published API v1.2.0 are supported.
Disclaimer: This project is not affiliated with, endorsed by, or officially connected to The MLC (Mechanical Licensing Collective). You need your own MLC Public Search API credentials to use it, and use of the API and its data remains subject to MLC terms.
- Auto-JSON when piped. Tables on a terminal, clean JSON the moment you pipe into
jqor a file.--jsonforces it. - Stable exit codes.
0ok,1request or input error,2auth or usage,3not found,4rate limited. Agents can branch without scraping stderr. - stdout is data, stderr is diagnostics.
mlc ... > out.jsonnever mixes logs into the payload. - No surprises with credentials. Tokens live in memory only, error bodies are never printed, and
mlc doctortells you exactly what is wrong. - Tab completion for bash, zsh, and fish.
macOS and Linux, no Rust toolchain required:
curl -sSL https://raw.githubusercontent.com/oneortwo/mlc-cli/main/install.sh | shThe script downloads the latest release for your platform into ~/.local/bin, verifies its SHA-256 checksum, and installs shell completions. Set MLC_INSTALL_DIR to install somewhere else.
Alternatives: download an archive from Releases (macOS Apple Silicon and Intel, Linux x86-64 and arm64), or build from source with stable Rust:
cargo install --git https://github.com/oneortwo/mlc-cli --lockedmlc updateDownloads the latest GitHub release for macOS or Linux (Intel/AMD and arm64), verifies its SHA-256 checksum, and atomically replaces the running executable. No MLC credentials are needed. It never downgrades a newer installation. Existing shell completion files are refreshed and release notes go to stderr; piped output is JSON.
The executable directory must be writable. For installations managed by Cargo, you can also rerun cargo install --git https://github.com/oneortwo/mlc-cli --locked --force.
mlc auth setup # prompts for username and password, verifies them, saves them
mlc doctor # confirms login and data access
mlc search works 'Yesterday' --writer-last-name McCartneyRequest Public Search API access through The MLC. The API exchanges a username and password for tokens; bulk-feed credentials are separate.
mlc auth setup saves your credentials to ~/.mlc/config.toml, readable only by your user. It verifies them against the API first, so a typo never gets saved. For scripts, CI, and agents, set MLC_USERNAME and MLC_PASSWORD instead; they take precedence over the file, and mlc auth setup --no-input saves them without prompting.
mlc auth status # shows whether credentials come from the environment or the file
mlc doctor # logs in and runs one small read-only searchNeither command prints credentials or tokens. Each command obtains fresh tokens, which are never written to disk. The data endpoints require the returned JWT idToken as the bearer token (verified against the live API); the returned accessToken is rejected.
mlc search works 'Yesterday' --writer-last-name McCartney
mlc search works 'YOUR_TITLE' --writer-ipi YOUR_WRITER_IPI
mlc search recordings --isrc GBAYE0601477
mlc search recordings --title Yesterday --artist 'The Beatles'
mlc work get MLC_SONG_CODE
mlc work batch FIRST_MLC_SONG_CODE SECOND_MLC_SONG_CODE
mlc --json search works 'Yesterday' --writer-last-name McCartney
mlc search works 'Yesterday' --writer-last-name McCartney | jq '.[].mlcSongCode'
mlc completions zsh > _mlcReplace placeholders with actual titles and identifiers. Search criteria are combined in one API request. Work searches require a title and at least one writer field; the live API rejects title-only and writer-only requests, although its schema does not mark those requirements. Work searches support one writer filter per invocation. Use the API's exact identifiers, including leading zeros.
Collections display as tables in a terminal; piped output and --json use JSON. Single-work details use formatted JSON to preserve nested writer/publisher ownership chains. Unknown response fields are preserved.
MLC's published API exposes no pagination or total-count parameters. The CLI returns the API response as received; a search is not a guaranteed complete catalog export. Requests time out after 60 seconds. Rate limits are reported without automatic retries.
| API | Command |
|---|---|
POST /oauth/token |
Automatic authentication; mlc auth setup, mlc doctor |
POST /search/songcode |
mlc search works TITLE --writer-last-name NAME (also --writer-first-name and --writer-ipi) |
POST /search/recordings |
mlc search recordings [--isrc ISRC] [--title TITLE] [--artist ARTIST] |
GET /work/id/{id} |
mlc work get ID |
POST /works |
mlc work batch ID... |
The batch request intentionally uses mlcsongCode, matching the API specification's spelling. This tool does not register works, manage claims, or download the bulk database.
| Code | Meaning |
|---|---|
| 0 | Success, including empty results |
| 1 | Network, response, input-value, or local I/O error |
| 2 | Authentication/configuration failure, or command-line usage error |
| 3 | HTTP 404 / not found |
| 4 | HTTP 429 / rate limited |
Credentials are stored in plain text in your local config with owner-only permissions; tokens are held in memory only. Requests use HTTPS to the fixed MLC API host and never follow redirects. HTTP error bodies are not printed. Tokens are redacted if they ever appear in a data response. Do not put credentials, local config, or real API-response fixtures in Git. See SECURITY.md.
MLC_API_URL overrides the API host. It exists for tests and proxies; leave it unset for normal use.
make check # fmt, clippy, tests
make build
make installTests use synthetic credentials and local mock HTTP servers; no MLC account is required. Pushing a v* tag publishes macOS (Apple Silicon and Intel) and Linux (x86-64 and arm64) archives with SHA-256 checksums through GitHub Actions.
MIT licensed. See CONTRIBUTING.md to get involved.