stenodict-cli

Tools for building and modifying stenography dictionary files, with Plover-focused workflows.

CLI

Install from PyPI:

pip install stenodict-cli

Commands:

• convert - Convert Markdown dictionaries to JSON.
• expand - Expand a template using entry sources to create a JSON dictionary that contains all combinations.
• remap - Remap strokes in JSON dictionaries to exclude strokes that appear in given Markdown dictionaries.
• merge - Merge Markdown and JSON dictionaries into one JSON output.

convert

Converts one or more Markdown sources into JSON. If --output is a .json file, all inputs are merged into that file. If --output is a directory, each source is converted to a separate JSON file preserving its relative path. Use --exclude to skip files or folders by regex.

stenodict convert \
  --input /path/to/md/sources \
  --input /path/to/extra/md \
  --output /path/to/output/json \
  --exclude "modifier-keys" \
  --quiet

stenodict convert \
  --input /path/to/md/sources \
  --output /path/to/output/combined.json

Input Format

Source files are Markdown documents that contain YAML code blocks:

# Navigation

## Navigation Keys

```yaml
-FPL: '{}{#up}' # Up
-RBG: '{}{#down}' # Down
-FR: '{}{#left}' # Left
-LG: '{}{#right}' # Right
```

expand

Expands template entries into a JSON dictionary that contains all combinations. Each template line defines an outline pattern and translation pattern using <outline> and <translation> placeholders. Each entry file provides outline → translation mappings that are substituted into the template to produce final dictionary entries. If --output is a .json file, the result is written there. If --output is a directory, the output filename matches the template source filename with a .json extension.

Templates and entries are Markdown files that contain YAML code blocks. You can also pass an inline template string. See the file format examples below.

stenodict expand \
  --template /path/to/modifier-keys.md \
  --entries /path/to/entries.md \
  --entries /path/to/extra-entries.md \
  --output /path/to/output/directory/ \
  --quiet

stenodict expand \
  --template /path/to/modifier-keys.md \
  --entries /path/to/entries.md \
  --output /path/to/output/modifier-keys.json

stenodict expand \
  --template "<outline>: '{^}<translation>'" \
  --entries /path/to/entries.md \
  --output /path/to/output/inline.json

Template Format

Use <outline> and <translation> placeholders in your template. Each entry in the entry files supplies both parts and will be expanded into a full stroke/translation pair.

# Modifier Keys

```yaml
PWA/<outline>: '{#option(<translation>)}' # Option
KPWA/<outline>: '{#option(control(<translation>))}' # Option+Control
SKPWA/<outline>: '{#option(control(shift(<translation>)))}' # Option+Control+Shift
```

Entries Format

Entry files are plain YAML mappings from outline to translation. These are the values substituted into <outline> and <translation> in the template.

# Keys

```yaml
A: '{^}a' # a
TPW-R: '{#F1}' # F1
-FRPB: '{}{#backspace}' # Backspace
K-BG: '{^,}' # Comma
KW-PL: '{?}' # Question Mark (Leading space)
```

remap

Remaps strokes in JSON dictionaries using stroke lists from .md files. --input and --entries accept a file or directory and can be repeated. If --output is a .json file, all inputs are merged into it. If --output is a directory, each input file is written to a corresponding output path. Use --exclude to skip stroke list files by regex.

stenodict remap \
  --input /path/to/input.json \
  --input /path/to/more/input.json \
  --entries /path/to/remap-md \
  --output /path/to/output.json \
  --quiet

Remap Entries Format

The remap entries inputs are Markdown documents that contain YAML code blocks.

# Keys

## Letters

```yaml
A: '{^}a' # a
AP: '{^}A' # A
-B: '{^}b' # b
P-B: '{^}B' # B
KR: '{^}c' # c
KR-P: '{^}C' # C
```

merge

Merges Markdown and JSON dictionaries into a single JSON output. Inputs can be .md or .json files, or directories that contain them. Use --exclude to skip files by regex. Use --on-conflict to control duplicate strokes (error, error-delete-output, keep-first, or keep-last). error-delete-output removes the output file before raising.

stenodict merge \
  --input /path/to/md \
  --input /path/to/dicts.json \
  --output /path/to/merged.json \
  --on-conflict keep-last \
  --quiet

Development

Set up a local environment with uv and run from source:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
stenodict --help

Install the pre-commit hook and run checks:

pre-commit install
pre-commit run --all-files

Testing

Run the test suite with pytest:

pytest