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 是一个终端工具，可搜索多个字体来源（GetFonts、DaFont、Fontshare、GitHub 等），对结果排序，并下载与你的查询最匹配的字体文件。