Documentation
Everything you need to know about using MKV Mender. New to the project? Start with our overview or try the web app.
🚀 Quick Start
Get started with MKV Mender in under 5 minutes
Install
Run the install script to get the CLI
Register
Create an account to contribute names
Rename
Look up and rename your media files
📦 Installation
Automatic Installation (Recommended)
The easiest way to install MKV Mender is using our install script:
Manual Installation
Download the binary for your platform from the releases page:
Build from Source
If you prefer to build from source, check out our GitHub repository:
Prefer not to install? Use our web application instead - no installation required.
🔐 Authentication
To upload names and vote, you need to create an account.
Register
Create a new account with a unique username:
⚠️ Important: Save your API key securely. It won't be shown again!
Login
Configure your API key for future commands:
Configuration File
Your credentials are stored at ~/.mkvmender/config.yaml:
🎬 Core Workflows
Looking Up Files
Query the community database for naming suggestions:
Renaming Files
Interactively select and apply a community-approved name:
💡 Tip: Use --dry-run to preview changes without applying them
Contributing Names
Submit your own naming conventions to help the community:
For TV shows, also include season and episode:
⚡ Advanced Features
Voting System
Vote on submissions to help identify the best naming conventions:
Search by Title
Find naming conventions without having the file:
Sort results by different criteria:
Batch Processing
Process entire directories at once. Perfect for organizing large media libraries:
Options for batch processing:
📚 Command Reference
mkvmender register
Create a new user account
| Flag | Description | Required |
|---|---|---|
--username |
Your desired username | Yes |
--url |
API base URL (default: https://mkvmender.org) | No |
mkvmender login
Configure API credentials
| Flag | Description | Required |
|---|---|---|
--api-key |
Your API key from registration | Yes |
--url |
API base URL | No |
mkvmender hash
Display SHA-256 hash of a file
mkvmender lookup
Query database for naming submissions
mkvmender rename
Interactively rename a file
| Flag | Description | Required |
|---|---|---|
--dry-run |
Preview changes without applying | No |
mkvmender upload
Submit a naming convention to the community
| Flag | Description | Required |
|---|---|---|
--type |
Media type: movie or tv | Yes |
--name |
Proposed filename | No |
--title |
Title of the media | No |
--year |
Release year | No |
--season |
Season number (TV only) | No |
--episode |
Episode number (TV only) | No |
--quality |
Video quality (e.g., 1080p, 4K) | No |
--source |
Source (e.g., BluRay, WEB-DL) | No |
mkvmender vote
Vote on naming submissions
mkvmender search
Search for titles without having the file
| Flag | Description | Default |
|---|---|---|
--sort |
Sort by: relevance, votes, date, title | relevance |
--no-fuzzy |
Disable fuzzy matching | false |
mkvmender batch
Process multiple files in a directory
| Flag | Description | Default |
|---|---|---|
--dry-run |
Preview changes without applying | false |
--ext |
File extensions to process (comma-separated) | .mkv,.mp4,.avi,.m4v |
🔧 Troubleshooting
Connection Errors
If you see "failed to connect to server":
- Check your internet connection
- Verify the base URL in
~/.mkvmender/config.yaml - Try running
mkvmender login --url https://mkvmender.org
Authentication Issues
If commands fail with "authentication required":
- Verify your API key is correct in the config file
- Try logging in again with
mkvmender login - If you lost your API key, register a new account
File Not Found
If you see "no submissions found for this file":
- This file hasn't been submitted to the database yet
- Be the first! Use
mkvmender uploadto contribute - Try searching by title instead:
mkvmender search "Movie Title"
Permission Errors
If you see permission errors when renaming:
- Ensure you have write permissions for the file's directory
- Try running the command with appropriate permissions
- Check if the file is currently open or in use by another program
❓ FAQ
How does the hashing work?
MKV Mender uses SHA-256 hashing of the entire file content. This means identical files will have the same hash, regardless of the filename. Even small changes to the file will result in a completely different hash.
Can multiple users submit names for the same file?
Yes! That's the whole point. The community votes to identify the best naming convention for each file. Popular submissions rise to the top.
Is my file uploaded to a server?
No! Only the file's SHA-256 hash and size are shared, along with your proposed filename. Your actual media files never leave your computer.
How do I change my username?
Currently, usernames cannot be changed. You would need to register a new account with a different username.
What's the difference between movies and TV shows?
TV shows require season and episode metadata. This allows for better organization and navigation when searching for specific episodes.
Can I delete my submissions?
Currently, only administrators can delete submissions. If you need a submission removed, please contact support or file a GitHub issue.
How can I contribute to the project?
Visit our GitHub repository to report issues, suggest features, or contribute code. We welcome all contributions!