CLI reference

The kotoshu command covers checking, setup, dictionaries, cache, your personal dictionary, and shell completions — plus a status overview. The four you will use most are below.

参照Reference

check

kotoshu check [FILE] [DIR ...] checks a file, a directory tree, or stdin when no target is given. It is cache-only — it never downloads. Run kotoshu setup LANG first; in a terminal, check offers to do that for you on a missing language.

echo "helo wrld" | kotoshu check
kotoshu check README.md --language de
kotoshu check README.md --format sarif
kotoshu check README.md --interactive

木歩Directory mode

Check a whole tree

Pass a directory and check walks it: every file with a known text extension — .md .markdown .asciidoc .adoc .txt .rst .mdx — is checked, one section per file in the output and a summary at the end. Explicit files and directories can be mixed; explicit files are checked as given, in argument order. Language detection runs per file, so a multilingual tree is fine.

$ kotoshu check .
# Detected: en.
# Detected: en.
FAIL ./README.md (2 errors)
helo -> hello, help, hell
readme -> ready, realm, redye

FAIL ./docs/guide.md (1 errors)
helo -> hello, help, hell

2 files checked, 4 words, 3 errors

JSON and SARIF formats emit one combined document over the whole walk — a files array in JSON, one SARIF run per file — so CI uploads a single report. Interactive mode stays file-only; on a directory target it prints an explicit notice instead.

The walker always skips hidden (dot-prefixed) files and directories, plus .git, node_modules, vendor and target, and honors .gitignore and .ignore files through a standard glob subset implemented in Ruby — no shelling out to git:

--include and --exclude select within the walk: include globs replace the extension default, exclude always wins, and both use the same glob conventions — no slash matches the basename, a slash matches the path from the checked root. Ignored files stay ignored: an include glob cannot resurrect a .gitignored file.

kotoshu check .                          # every known text extension in the tree
kotoshu check . --include "*.adoc"       # only .adoc files, anywhere in the tree
kotoshu check . --exclude "vendor/**/*"  # drop a subtree (note /**/* for nested files)
kotoshu check src README.md              # explicit files and directories, mixed

Baselines apply per file across the walk. One truth to know: the baseline matches the file path exactly as the check reports it — walking . yields ./docs/guide.md, so record the baseline with the same spelling of paths:

kotoshu baseline init ./*.md docs/**/*.adoc   # paths as the walk from . sees them
kotoshu check . --baseline .kotoshu-baseline.json

OK ./README.md (2 words, no errors)
2 error(s) suppressed by baseline

2 files checked, 4 words, 0 errors

The same walker selection backs rake kotoshu:check and the Jekyll generator — the integrations page covers both. Inline directives and the personal dictionary work in directory mode exactly as they do per file; see Ignores & baselines.

check has no offline flag because it needs none: it is cache-only by design and never downloads. To hold the whole session — setup included — to that promise, export KOTOSHU_OFFLINE=1. The --strict flag belongs to setup, where it turns optional-resource failures into a failed run.

setup

Stage one, as a command. Downloads spelling, frequency, and model resources — or registers .aff/.dic files you already have on disk. Idempotent; --force re-fetches and --strict turns optional-resource failures into a failed run. When the model is requested with --model, --tier selects its size — fluency (the default), full, or mini; the tiers are detailed in Caching & resources. With no arguments it lists what is set up.

kotoshu setup en                  # spelling only (~5 MB)
kotoshu setup en de fr            # several languages
kotoshu setup en --want spelling,frequency,model   # model defaults to fluency (~15 MB)
kotoshu setup en --model --tier mini   # model at the mini tier (~3 MB)

# Local files instead of downloads (--aff and --dic go together)
kotoshu setup en --aff en_US.aff --dic en_US.dic
kotoshu setup en --from /path/to/dict/dir/    # expects LANG.aff + LANG.dic
kotoshu setup en --frequency my-frequency.json

kotoshu setup --list              # what is already set up

The old kotoshu fetch spelling still works as a hidden, deprecated alias of setup.

cache

For a wider picture — setup, cache, and runtime state in one report — run kotoshu status.

baseline

kotoshu baseline init FILE [FILE ...] records the spelling errors a file has right now — one entry per file and word with the occurrence count, stable across reformatting — into .kotoshu-baseline.json (--output names another file). It takes -l/--language like check does.

kotoshu baseline init README.md docs/*.adoc
kotoshu baseline init src/*.txt --output .kotoshu-baseline.json

# CI: covered errors pass, new errors fail the build
kotoshu check README.md --baseline .kotoshu-baseline.json

Stale entries — debt you have since fixed — are reported in the summary so the budget shrinks visibly. The whole story, including JSON and SARIF output and the inline ignore directives, is on Ignores & baselines.

dict & personal

Two smaller surfaces round out the command. kotoshu dict list shows the available dictionary types and kotoshu dict info TYPE describes one. kotoshu personal manages the words only you use — the file lives at ~/.config/kotoshu/personal.dic (override with KOTOSHU_PERSONAL_DIC; kotoshu personal path prints wherever yours resolves).

kotoshu personal add Koordinatenverein strahlend     # two words, one command
kotoshu personal list
kotoshu personal import project-terms.txt     # one word per line
kotoshu personal path                          # where the file lives

completions

# bash (single user)
kotoshu completions bash > ~/.local/share/bash-completion/completions/kotoshu

# zsh — drop into any directory on your $fpath
kotoshu completions zsh > "${fpath[1]}/_kotoshu"

# fish
kotoshu completions fish > ~/.config/fish/completions/kotoshu.fish

# Supported language codes, no install needed
kotoshu completions languages

The language list is read dynamically, so newly registered languages complete without reinstalling the script.

Exit codes