README
¶
∧＿∧
（ ´∀｀） 文字 moji
（ ）
| | |
（_＿）＿）
moji
find and safely download fonts without leaving the terminal.
moji searches multiple font sources, ranks files by family and filename, and
downloads the match you actually asked for. use the Bubble Tea interface when
working interactively, a stable table in pipelines, or JSON when another tool
needs to consume the results.
the npm package includes native binaries for linux, macOS, and windows on x64 and arm64. installing Go is not required.
quick start
install with the package manager you already use:
npm install --global @microck/moji
pnpm add --global @microck/moji
bun add --global @microck/moji
search for a family:
moji
# or jump straight to results
moji "Inter"
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 "Inter" --format otf,ttf
moji "Inter" --format woff2 --json
download the best match, preview the choice first, or ask for the whole family:
moji get "Inter bold" --dry-run
moji get "Inter bold"
moji get "Inter entire family" --download-dir ~/Downloads/moji
providers
the default GetFonts provider works without an account. GitHub Code Search
requires authentication, so moji activates it only when GITHUB_TOKEN or
github_token is configured.
export GITHUB_TOKEN=github_pat_example
moji "Inter" --provider github
do not pass tokens as command-line flags. use --token-stdin when a token only
needs to exist for one invocation.
SearXNG search is also available, but it stays disabled until both the provider and an instance URL are 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 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.
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]
providers:
github:
enabled: true
getfonts:
enabled: true
websearch:
enabled: false
instance: ""
documentation
the Fumadocs site covers the complete workflow:
- start here
- tutorial
- CLI reference
- configuration reference
- providers
- errors and exit codes
- architecture
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
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.
Directories