moji README

The project's README from github.com/Microck/moji. As one markdown file: README.md.

moji

moji

npm version badge npm total downloads badge ci badge MIT license badge

https://github.com/user-attachments/assets/33fafa72-7974-4fb1-b107-98bfef03194a

ask for a font and get the file you actually meant. moji searches across font sources, ranks candidates by family and filename, and downloads the best match. browse interactively with Bubble Tea, pipe a stable table into shell workflows, or request JSON for programmatic use.

quick start

install with the package manager you already use:

npm install -g @microck/moji
pnpm add -g @microck/moji
bun add -g @microck/moji

or install the same released native binary from this repository's Homebrew formula:

brew tap microck/moji https://github.com/Microck/moji
brew install microck/moji/moji

The explicit tap URL is required because this source repository is not named homebrew-moji. Upgrade later with brew upgrade microck/moji/moji.

search for a family:

moji
# or jump straight to results
moji "Futura"

bare moji opens the home TUI so you can type a query. pass a query to jump straight to the live result list. redirect or pipe a queried command to get a stable table instead.

moji "Futura" --format otf,ttf
moji "Futura" --format woff2 --json

download the best match, preview the choice first, or ask for the whole family:

moji get "Futura bold" --dry-run
moji get "Futura bold"
moji get "Futura entire family" --download-dir ~/Downloads/moji

convert a local desktop font to WOFF2, or restore a WOFF2 font to the TTF or OTF flavor stored inside it:

moji convert Inter.ttf
moji convert Inter.woff2
moji convert Inter.otf --to woff2 --output build/Inter.woff2

conversion detects the input from its content and never replaces an existing output file. it changes the font container without changing TrueType or CFF glyph outlines.

inspect a downloaded TTF, OTF, or WOFF2 font before using it:

moji inspect Inter.ttf
moji inspect Inter.woff2 --json

inspection reads the font's character map and reports exact Unicode script coverage counts. This answers whether a font includes Cyrillic, Arabic, Han, or another script without relying on its filename.

providers

the default GetFonts, DaFont, Fontshare, and registry providers work without an account. DaFont search results are parsed from its public catalog and direct ZIP downloads pass through Moji's normal archive safety limits. Font Squirrel is available through --provider fontsquirrel, but is off by default because its site protection can block API clients. All catalog providers inspect source download archives for the formats you requested. GitHub's repository, tree, and release search also uses its small unauthenticated allowance. Moji automatically uses an existing authenticated gh session when GitHub CLI is installed. GITHUB_TOKEN and github_token take precedence and also enable Code Search and higher limits. the TUI points this out when GitHub search is limited.

the websearch provider automatically uses kagi-cli when it is installed. Run kagi auth once. Ordinary web pages are ignored. direct CSS font URLs and bounded ZIP or TAR archive members can become results. configured source plugins pass through the same HTTPS, format, and download validation boundary. Direct binary responses with missing or misleading extensions can also be recognized as ZIP, TAR, or compressed TAR archives by signature; webpages and interactive download flows remain excluded.

export GITHUB_TOKEN=github_pat_example
moji "Futura" --provider github

do not pass tokens as command-line flags. use --token-stdin when a token only needs to exist for one invocation.

the same websearch provider also uses SearXNG when an instance URL is configured.

commands

command purpose
moji open the home TUI and type a font query
moji <query> search interactively or print a table when piped
moji get <query> rank results and download the best match
moji convert <input> convert TTF/OTF to WOFF2 or restore WOFF2
moji inspect <input> report Unicode script coverage for a local font
moji config create the default config when needed and open $EDITOR
moji config show print the current config with its token redacted
moji cache clear remove cached provider results

run moji --help for the complete flag and example reference.

download safety

downloads use HTTPS by default and stop at 50 MiB. before the final file appears, moji validates its font magic bytes, sanitizes its filename, writes to a temporary path, and renames it atomically. SHA-256 hashes prevent duplicate files from being saved twice.

If the first ranked link returns invalid font bytes, moji get remembers that URL and tries the next candidate. Whole-family downloads validate one coherent same-source group in staging, so a broken member cannot leave a partial family or mix sources.

search results include source and best-effort license metadata. an unknown license is not permission to use or redistribute a font. check the font's license before shipping it.

configuration

the default config lives at ~/.moji/config.yaml and is written with mode 0600. set MOJI_CONFIG to use a different file.

download_dir: ~/Downloads/moji
search_timeout_seconds: 15
cache_ttl_seconds: 3600
default_formats: [otf, ttf, woff2, dfont, pfb, pfm]
source_plugins: []

providers:
  github:
    enabled: true
  getfonts:
    enabled: true
  dafont:
    enabled: true
  fontsquirrel:
    enabled: false
  fontshare:
    enabled: true
  registry:
    enabled: true
  websearch:
    enabled: true
    instance: ""

documentation

the Fumadocs site covers the complete workflow:

the original product and architecture research remains in research/cli-design.md.

development

verify the Go CLI and production documentation build together:

npm install
npm run verify

run the parts independently when working on one side of the repository:

make verify
npm run docs:check
npm run docs:build
npm run docs:dev

Before a release, npm run release rebuilds and verifies the exact npm archive without publishing it. The operator-only npm run release:publish runs the same gate before npm publication, the annotated tag, and the GitHub release. See the release runbook.

the end-to-end suite builds the real binary, searches a controlled HTTP provider, downloads a valid fixture font, checks the file on disk, and exercises cache clearing. conversion tests use FontTools fixtures, and CI runs a pinned FontTools interoperability check in both directions.

license

MIT

moji (Microck/moji)

Searching Database…

257 ·GitHub
Moji
What is this?Moji is a terminal tool that searches multiple font sources (GetFonts, DaFont, Fontshare, GitHub, and more), ranks the results, and downloads the font file that best matches your query.
Is this a plain CLI, or does it have its own interface?It is both: running 'moji' with no arguments opens an interactive Bubble Tea TUI, while piping a query prints a stable table or JSON for scripting.
How do I install it and start searching?Install via your usual package manager or this repo's Homebrew formula with the explicit tap, e.g. 'brew install microck/moji/moji', since the repo isn't named homebrew-moji. After that, run 'moji' to open the TUI or 'moji ' to search directly.
Do I need any accounts or tokens just to search?No — the default GetFonts, DaFont, Fontshare, and registry providers work without an account. GitHub search and the websearch provider (via kagi-cli or SearXNG) are optional extras that each need their own auth.
Any providers or downloads I should watch out for?Font Squirrel is disabled by default because its site protection can block API clients, downloads are capped at 50 MiB with font-magic-byte validation before being kept, and license metadata is only best-effort so you should verify a font's license before redistributing it.
Does it work the same on Linux, macOS, and Windows?Yes — moji ships as native binaries distributed through both npm and Homebrew, so the same tool runs on Linux, macOS, and Windows without extra setup.
Can moji convert fonts between formats?Yes, 'moji convert' turns TTF/OTF into WOFF2 and can restore a WOFF2 back to the TTF or OTF outline stored inside it, without altering the glyph outlines.
What does 'moji inspect' tell me about a font?It reads the font's character map and reports exact Unicode script coverage, so you can check whether a font supports scripts like Cyrillic, Arabic, or Han without guessing from the filename.
How does moji avoid saving duplicate font files?It computes SHA-256 hashes of downloaded files, so the same font won't be saved twice even across different searches.
What happens if the top search result turns out to be a bad file?moji validates the font's magic bytes after download; if the first ranked link returns invalid font bytes, it remembers that URL and automatically tries the next candidate.
What are similar projects?veet, cliamp, fx, ripgrep, yoinks, gh-dash, tuios, sampler
Which topics is it in?bubbletea, converter, font, typography, downloader, package-manager, search, homebrew, tui, json, command-line, go
Creator
Microck
Size
7.7 MB
Stars
257
Updated
CommitAug 30Releasev0.8.0Aug 30
Age
3mo
Commits · 90 Days