# wordsmith-cli
[](https://crates.io/crates/wordsmith-cli)
[](https://opensource.org/licenses/MIT)
Command‑line word lookup tool with multiple sources: **formal dictionary** (dictionaryapi.dev), **Urban Dictionary**, Datamuse (synonyms/antonyms), and a **Gen Alpha dictionary**. Records your lookups to Markdown/JSONL logs and can render the log with `glow` if available.
---
## Features
- Formal definitions via **dictionaryapi.dev**
- Slang/colloquial definitions via **Urban Dictionary**
- Thesaurus lookups (synonyms/antonyms) via **Datamuse**
- Optional Gen Alpha lookup via **gen_alpha_dictionary**
- Markdown **and** JSONL logging with timestamps
- View the log in the terminal (uses `glow` when installed; falls back to plain text)
- Tilde expansion for `--log-dir` (e.g., `~/.local/share/...`)
> Note: There is **no configuration file** and **no offline cache** at present.
---
## Installation
```bash
cargo install wordsmith-cli
```
---
## Usage
```
Word lookup CLI: formal defs, Urban Dict, synonyms/antonyms, logs
Usage: wordsmith-cli [OPTIONS] [WORD]
Arguments:
[WORD] The word to define
Options:
--log View the log instead of looking up a word
--formal Run formal dictionary lookup
--urban Run Urban Dictionary lookup
--thesaurus Run thesaurus (synonyms/antonyms)
--gen-alpha Run Gen Alpha dictionary lookup
--no-log Do not record this lookup
--log-dir <LOG_DIR> Directory for log.md and log.jsonl [default: ~/.local/share/wordsmith-cli]
-h, --help Print help
```
### Behavior
- If **no** feature flags are provided (no `--formal/--urban/--thesaurus/--gen-alpha`), the tool runs **all** lookups that are supported.
- Lookups are logged unless `--no-log` is provided.
- `--log` shows the log instead of performing a lookup.
### Examples
Run everything (formal, Urban, thesaurus, Gen Alpha if compiled/available):
```bash
wordsmith-cli luminous
```
Formal dictionary only:
```bash
wordsmith-cli --formal luminous
```
Urban Dictionary only:
```bash
wordsmith-cli --urban sus
```
Thesaurus (synonyms/antonyms) only:
```bash
wordsmith-cli --thesaurus chaos
```
Gen Alpha dictionary only:
```bash
wordsmith-cli --gen-alpha rizz
```
Skip logging for a single lookup:
```bash
wordsmith-cli --no-log ephemeral
```
Specify a custom log directory:
```bash
wordsmith-cli --log-dir "~/.local/share/wordsmith-cli-test"
```
View the log (uses `glow --width 200` when available, otherwise prints the file):
```bash
wordsmith-cli --log
```
---
## Output & Logging
Lookups print definitions and, when available, an example section plus **Synonyms** and **Antonyms** lists.
Two log files are maintained (created as needed) under `--log-dir` (default: `~/.local/share/wordsmith-cli`):
- `log.md` — Markdown table:
```markdown
# Wordsmith Log
| Date | Word | Definition | Synonyms | Antonyms |
|---|---|---|---|---|
| 2025-10-21 14:12:10 | luminous | emitting or reflecting light | bright, radiant | dark, dim |
```
- `log.jsonl` — one JSON object per line, including flags indicating which sources returned results.
---
## Acknowledgements
- [`gen_alpha_dictionary`](https://crates.io/crates/gen_alpha_dictionary) — additional dictionary source
- [`glow`](https://crates.io/crates/glow) — pretty Markdown rendering in terminal
- [`clap`](https://crates.io/crates/clap) — CLI parsing
- [`reqwest`](https://crates.io/crates/reqwest), [`serde`](https://crates.io/crates/serde), [`serde_json`](https://crates.io/crates/serde_json) — HTTP/JSON plumbing
- [`chrono`](https://crates.io/crates/chrono) — timestamps
- [`textwrap`](https://crates.io/crates/textwrap) — tidier text wrapping
- Data/API sources: **dictionaryapi.dev**, **urbandictionary.com**, **datamuse.com**
---
## License
MIT — see [LICENSE](./LICENSE).
---
## Contributing
Issues and PRs are welcome.