mdx-cli

Command-line MDX dictionary lookup tool

English · 简体中文

▶ Install: pipx install git+https://github.com/rockbenben/mdx-cli.git — then mdx init ~/Dictionaries and you're looking words up. Needs Python 3.10+.

A fast, modern command-line dictionary tool for MDX files. Fuzzy search, multi-dictionary, colored output, pipe-friendly.

$ mdx hello
━━━ OALD ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
hello  /həˈləʊ/

 1. used as a greeting
    • Hello, how are you?
    • Say hello to your sister for me.

 2. used when answering the telephone
    • Hello? Who's speaking?
━━━ LONGMAN ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
hello  /hɛˈloʊ/
  ...

What is MDX?

MDX is an offline dictionary format used by MDict, Eudic, GoldenDict and similar apps. Plenty of dictionaries are distributed in it (Oxford, Longman, Collins…) — download one and you can look words up with no network at all.

mdx-cli lets you query those files straight from the terminal instead of opening a GUI.

Supported platforms

Platform	Support	Audio playback
Windows 10/11	Full	Built-in PowerShell (MP3/WAV), or install mpv
macOS	Full	Built-in afplay, or install mpv
Linux	Full	Needs one of mpv, paplay or aplay

Behaviour is identical everywhere and the config file format is the same.

Features

• Fuzzy search -- exact match, prefix, and FTS5 trigram substring search with automatic fallback
• Multi-dictionary -- query multiple MDX dictionaries at once, sorted by priority
• Colored output -- Rich terminal rendering with bold, italic, lists; auto-degrades in pipes
• Pipe-friendly -- --json, --raw, auto plain-text when piped
• Fast -- SQLite index with mtime-based cache; sub-millisecond repeated lookups
• Interactive REPL -- tab completion, history, quick dict/group switching
• Audio playback -- pronounce words from MDD resources (cross-platform)

Install

pipx install git+https://github.com/rockbenben/mdx-cli.git

Or with pip:

pip install git+https://github.com/rockbenben/mdx-cli.git

Requires Python 3.10+. Not on PyPI yet — install straight from the repo.

Quick Start

# Scan a directory for MDX files and register them
mdx init ~/Dictionaries

# Look up a word
mdx hello

# Specify a dictionary
mdx hello -d oald

# Query multiple dictionaries
mdx hello -d oald -d longman

# Fuzzy search (substring match)
mdx ello --fuzzy

# JSON output (for scripts)
mdx hello --json

# Play pronunciation
mdx hello --play

# Interactive mode
mdx repl

Configuration

Config file: ~/.config/mdx-cli/config.toml

[general]
default_dicts = ["oald", "longman"]
fuzzy_threshold = 3
pager = true                           # (reserved, not yet implemented)

[dict.oald]
path = "/path/to/oald.mdx"
priority = 1

[dict.longman]
path = "/path/to/longman.mdx"
priority = 2

[groups.english]
dicts = ["oald", "longman"]

Dictionary Management

mdx add /path/to/dictionary.mdx           # Add a dictionary
mdx add /path/to/dictionary.mdx -a mydict # Add with custom alias
mdx list                                   # List registered dictionaries
mdx rebuild                                # Rebuild all indexes
mdx rebuild oald                           # Rebuild one index

Search Behavior

Queries cascade through three strategies:

1. Exact match -- case-insensitive, instant
2. Prefix match -- hel finds hello, help, helicopter
3. Trigram substring -- ello finds hello (FTS5 trigram tokenizer)

Use --fuzzy to skip directly to trigram search.

Output Formats

Mode	When	Example
Rich	Terminal (tty)	Colored, styled, with rules
Plain	Piped (mdx hello | less)	Auto-detected, no ANSI codes
JSON	--json	Structured data with phonetic, html, text
Raw	--raw	Original HTML from MDX

JSON output:

{
  "query": "hello",
  "results": [
    {
      "dict": "oald",
      "headword": "hello",
      "phonetic": "/həˈləʊ/",
      "html": "<p>...</p>",
      "text": "plain text definition"
    }
  ]
}

REPL Mode

$ mdx repl
mdx repl — type a word to look up, :q to quit
mdx> hello
━━━ OALD ━━━━━━━━━━━━━━━━━━
  ...
mdx> :d longman        # switch dictionary
mdx> :g english        # switch to group
mdx> :play             # replay last pronunciation
mdx> :history          # recent lookups
mdx> :q                # quit

Tab completion works -- type a few letters and press Tab.

Architecture

CLI (click) ─> DictMgr ─> Searcher ─> SQLite (FTS5)
                  │            │
                  v            v
              Indexer      Formatter ─> Rich / Plain / JSON / Raw
                  │            │
                  v            v
            Reader        Renderer (HTML ─> terminal)
          (readmdict)

• Reader wraps readmdict for MDX/MDD parsing
• Indexer builds SQLite databases with FTS5 trigram indexes (atomic writes, mtime caching)
• Searcher cascades exact/prefix/fuzzy queries
• Renderer converts HTML definitions to terminal-friendly Rich text
• Formatter dispatches output to the appropriate format
• DictMgr coordinates indexing, caching, and multi-dictionary queries

FAQ

mdx isn't found after installing

Make sure Python's Scripts directory is on your PATH:

• Windows: usually C:\Users\<you>\AppData\Roaming\Python\Python3x\Scripts
• macOS / Linux: usually ~/.local/bin

Or just run python -m mdx_cli instead of mdx.

A lookup returns nothing

1. Check the dictionary is registered: mdx list
2. If the list is empty, run mdx init <path to your dictionary folder>
3. Check the .mdx file path is right

The first lookup is slow

That's expected — the first query against a dictionary builds its SQLite index. Later lookups against the same dictionary are sub-millisecond.

Pronunciation plays no sound

1. Confirm the .mdd file has the same name as the .mdx and sits in the same folder
2. Check the system has a usable player:
   • Windows: built-in PowerShell playback (nothing to install)
   • macOS: built-in afplay (nothing to install)
   • Linux: install mpv (sudo apt install mpv)
3. If mpv or ffplay is installed it's preferred on every platform

Development

git clone https://github.com/rockbenben/mdx-cli.git
cd mdx-cli
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
python -m pytest -v

101 tests covering all modules.

About the 365 Open Source Plan

Project #004 of the 365 Open Source Plan — one person + AI, 300+ open-source projects in a year. Submit your idea → · Discord · Telegram