dictomatic

Static, offline, command-line CLI dictionary

Demo

Provide a word, get the definitions back in a tab-delimited table:

$ dictomatic.exe snag
snag    noun    an unforeseen obstacle  -
snag    noun    an opening made forcibly as by pulling apart    -
snag    noun    a sharp protuberance    -
snag    verb    hew jaggedly    -
snag    verb    catch on a snag I snagged my stocking
snag    verb    get by acting quickly and smartly       snag a bargain

Features

• Definitions from the Wordset Project, which is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License
• Statically compiled, word lists are linked in. No dependencies. Just download an executable for your target platform.
• Fast; a lookup completes in well under a millisecond (sub-millisecond end-to-end, dominated by process startup rather than the lookup itself). The word list and definitions are indexed at build time, so there is no per-invocation parsing — just a binary search over data baked into the binary. This makes it easy to drive from your editor, and works offline.

Install

Download a prebuilt binary

The simplest option: grab the executable for your platform from the Releases page. Each release ships binaries for Linux (x86-64 glibc and static musl, plus aarch64 musl), macOS (Intel and Apple Silicon), and Windows (x86-64). The download badges above link to the x86-64 Linux and Windows builds of the latest release.

Install with cargo

dictomatic is not published to crates.io, so the bare cargo install dictomatic and cargo binstall dictomatic forms will not work. Point cargo at this GitHub repository by URL instead:

# Prebuilt binary via cargo-binstall (no compilation; downloads the release
# binary built by CI). Requires https://github.com/cargo-bins/cargo-binstall
cargo binstall --git https://github.com/cjrh/dictomatic dictomatic

# Or compile and install from source (needs a Rust toolchain):
cargo install --git https://github.com/cjrh/dictomatic

cargo binstall --git reads this repo's Cargo.toml, which tells it where the release binaries live ([package.metadata.binstall]), and installs the prebuilt dictomatic for your platform. cargo install --git instead builds from source, embedding the word lists into a fresh binary.

Overview

The demo output further up looks a bit odd in the demo above because the sections are separated by tabs \t. Tabs work well as a separator in text-based applications because they almost never appear in text. This output format is designed to be easy to use in unix command-line pipelines.

There are always four sections (separated by tabs) in each line:

WORD    POS     DEFINITION                              EXAMPLE
snag    verb    get by acting quickly and smartly       snag a bargain

If a section is missing, it will appear as a single -. For instance, there are not example usages of snag in the noun form, but there is one example usage for snag as a verb: snag a bargain.

Multiple words

Multiple words are supported, because it might be convenient to see a bunch of related definitions at the same time:

$ dictomatic.exe word wordy words
word    noun    a unit of language that <snip>  Words are the blocks from which sentences<snip>
word    noun    information about recent<snip   What's the word on the new smart phone?
word    noun    a secret word or phrase <snip>  I forgot the word, but can you still let me in?
word    noun    a brief statement               I didn't say a word about it to anyone.
word    noun    an exchange of views on <snip>  We sat down and had words about politics.
word    noun    a verbal command for act<snip>  When I give the word, charge!
word    noun    a highly valued promise         I gave my word to you, yet you still mana<snip>
word    noun    a string of bits stored <snip>  Large computers use words up to 64 bits long.
word    verb    to put into words or an <snip>  I worded my apology badly.

wordy   adjective       using or containing too many words      -

words   noun    language that is spoken <snip>  They have a gift for words.
words   noun    words making up the dial<snip>  -
words   noun    the text of a popular so<snip>  -
words   noun    the words that are spoken       I listened to their words very closely.
words   noun    an angry dispute                -

This is why the the word itself appears in the results: so that downstream pipeline applications can do things with it.

Pipeline processing

If you don't supply any words as arguments, it will read a list of words from stdin. For instance, given a file test.txt with contents rust\ngold:

$ cat test.txt | dictomatic.exe
rust    adjective       of the brown color of rust      -
rust    noun    any of various fungi causing rust disease in plants    <all snipped>
rust    noun    the formation of reddish-brown ferric oxides on iron
rust    noun    a plant disease that produces a reddish-brown discol
rust    noun    a red or brown oxide coating on iron or steel caused
rust    verb    become coated with oxide        -
rust    verb    become destroyed by water, air, or a corrosive such 
rust    verb    cause to deteriorate due to the action of water, air

gold    adjective       having the deep slightly brownish color of g
gold    adjective       made from or covered with gold  gold coins
gold    noun    a deep yellow color     -
gold    noun    something likened to the metal in brightness or prec
gold    noun    great wealth    Whilst that for which all virtue now
gold    noun    coins made of gold      -
gold    noun    a soft yellow malleable ductile (trivalent and univa

This means that other programs that can emit "one word per line" can feed that output into dictomatic.

Tips & Tricks

Take advantage of CLI filters! How about extracting only the parts of speech:

$ dictomatic.exe jump | cut -f2
noun
noun
noun
noun
noun
noun
verb
verb
verb
verb
verb
verb
verb
verb
verb
verb
verb
verb
verb
verb
verb

Count the parts of speech (awk NF to drop the blank line):

$ dictomatic.exe jump | awk NF | cut -f2 | sort | uniq -c
      6 noun
     15 verb

Filter definitions and extract the definition only:

$ dictomatic.exe jump | grep attack | cut -f3
make a sudden physical attack on

Extract only definitions and remove punctuation:

$ dictomatic.exe jump | cut -f3  | tr -d [:punct:]
the act of jumping
descent with a parachute
a sudden involuntary movement
film an abrupt transition from one scene to another
an abrupt transition
a sudden and decisive increase
go back and forth
rise in rank or status
increase suddenly and significantly
pass abruptly from one state or topic to another
bypass
enter eagerly into
make a sudden physical attack on
start a car engine whose battery is dead by connecting it to another cars battery
move or jump suddenly as if in surprise or alarm
move forward by leaps and bounds
cause to jump or leap
jump from an airplane and descend with a parachute
run off or leave the rails
jump down from an elevated point
be highly noticeable

Extract only usage-examples (filtering out -), with the part-of-speech in trailing brackets:

$ dictomatic.exe jump | awk NF | awk -F '\t' '$4!="-"{ print $4 " [" $2 "]" }'
a jump in attendance [noun]
My new novel jumped high on the bestseller list. [verb]
Prices jumped overnight [verb]
We jumped into the game. [verb]
The muggers jumped the couple coming out of the gallery. [verb]
the trainer jumped the tiger through the hoop [verb]
the parachutist didn't want to jump [verb]

The full roundtrip, where we

• find definitions of "jump",
• filter those by appearance of the word "sudden",
• remove punctuation,
• convert spaces to newlines (so each word in the definition is on its own line),
• remove duplicates,
• filter for words longer than 8 characters,
• and feed back into dictomatic for definitions of those words!!

$ dictomatic.exe jump \
    | cut -f3 \
    | grep sudden \
    | tr -d [:punct:] \
    | tr [:blank:] '\n' \
    | sort -u \
    | awk 'length($0) > 8' \
    | dictomatic.exe
involuntary     adjective       not subject to the control of the will  involuntary manslaughter
involuntary     adjective       controlled by the autonomic nervous system      -

significantly   adverb  in a significant manner our budget will be significantly affected by these new cuts
significantly   adverb  in an important way or to an important degree   -
significantly   adverb  in a statistically significant way      the two groups differed significantly

Cutting a release (maintainers)

Releases are cut with cargo release. You run a single command locally; GitHub Actions builds and publishes the binaries. The flow is: cargo release bumps the version and pushes a vX.Y.Z tag → the tag triggers the Release workflow (.github/workflows/release.yml) → the workflow builds the binaries and attaches them to a GitHub Release.

One-time setup

cargo install cargo-release

This crate is distributed as prebuilt binaries via GitHub Releases, not via crates.io. publish = false is set in Cargo.toml, so cargo release automatically skips the crates.io publish step — there is nothing extra to configure or pass on the command line.

Cut a release

From a clean checkout of master:

# Dry run first: cargo release changes nothing without --execute.
cargo release patch

# Happy with the plan? Run it for real:
cargo release patch --execute

Use patch, minor, or major (or an explicit version such as 0.2.0) to choose how the version is bumped.

What happens

When run with --execute, cargo release will:

1. Bump version in Cargo.toml and Cargo.lock (e.g. 0.1.0 → 0.1.1).
2. Commit that change.
3. Create a git tag named vX.Y.Z (e.g. v0.1.1). The leading v is the default for this single-crate repo, and it matters — see the note below.
4. Push the commit and the tag to GitHub.

Pushing the tag triggers the Release workflow, which then:

5. Builds the binaries from that tag across three runners, naming each asset with its Rust target triple. The matrix covers:
   • Linux x86-64 — dictomatic-x86_64-unknown-linux-gnu and a static dictomatic-x86_64-unknown-linux-musl.
   • Linux aarch64 — a static dictomatic-aarch64-unknown-linux-musl.
   • macOS — dictomatic-x86_64-apple-darwin (Intel) and dictomatic-aarch64-apple-darwin (Apple Silicon).
   • Windows x86-64 — dictomatic-x86_64-pc-windows-msvc.exe.
6. Creates a GitHub Release for the tag and uploads every binary as an asset.

The non-native targets are cross-compiled with rustup target add (and rust-lld for the static musl builds), so the whole matrix runs on the three standard GitHub runners — no cross/QEMU or cross-toolchains needed.

What gets created, and where

• A git tag vX.Y.Z in the repository.
• A GitHub Release for that tag, listed at https://github.com/cjrh/dictomatic/releases.
• One downloadable asset per target on that release, e.g. https://github.com/cjrh/dictomatic/releases/download/vX.Y.Z/dictomatic-aarch64-apple-darwin.

The target triple in the asset name is what lets cargo binstall find the right binary for each platform.

Tag naming. The Release workflow only fires for tags matching v* (see on.push.tags in release.yml). cargo release already produces this vX.Y.Z form by default, so no extra configuration is needed.

Badges. The download badges at the top of this README link through releases/latest/download/..., which GitHub redirects to the newest release. They track new releases automatically — no per-release edit needed.