Two ways to install
Download a ready-made binary, or build it with Rust.
① Download a release (recommended)
Take the archive for your platform from GitHub Releases. Unpack it and you have a single executable — nothing else to install.
- Seven platforms are prebuilt
- SHA-256 checksums included
- You place it on PATH yourself
② Build from source
With a Rust toolchain, cargo install is one line, and updating later is easy.
- Needs Rust 1.85 or newer
- Installs into Cargo's bin directory, usually already on PATH
- The first build takes a few minutes
There is no installer, no service, no registry entry, and no configuration scattered around the system. The only file it reads on its own is a key profile (see 4.1.7), and it runs perfectly well without one; the only files it writes are documents you save and the phrase and macro JSON you ask it to write (see 2.4.5). To uninstall, delete the executable.
Download the right archive
Check which CPU you actually have, then match the filename.
Go to github.com/walisayu/erya/releases/latest and pick a .tar.gz:
| System | Architecture | Release target (in the filename) |
|---|---|---|
| Linux | Intel / AMD 64-bit | x86_64-unknown-linux-gnu |
| Linux / Raspberry Pi OS 64-bit | ARM64 | aarch64-unknown-linux-gnu |
| Raspberry Pi OS 32-bit | ARMv7 hard-float | armv7-unknown-linux-gnueabihf |
| macOS | Intel | x86_64-apple-darwin |
| macOS | Apple silicon | aarch64-apple-darwin |
| Windows | Intel / AMD 64-bit | x86_64-pc-windows-msvc |
| Windows | ARM64 | aarch64-pc-windows-msvc |
If you are not sure which you have
- macOS: run uname -m. arm64 is Apple silicon, x86_64 is Intel.
- Linux / Raspberry Pi: also uname -m. aarch64 → ARM64, armv7l → ARMv7, x86_64 → Intel/AMD.
- Windows: Settings → System → About → System type.
The Pi 4 and 5 have 64-bit CPUs, but Raspberry Pi OS also ships a 32-bit build. A 32-bit system needs the ARMv7 archive; the ARM64 one will not run. uname -m reports what the system actually is, which is the number that matters.
Verify it and put it on PATH
Unpacking gives you one file: erya (erya.exe on Windows).
Every archive ships a matching .sha256, and the release page has a combined SHA256SUMS. To check that the download is intact:
| System | Command |
|---|---|
| macOS | shasum -a 256 erya-*.tar.gz |
| Linux | sha256sum -c erya-*.tar.gz.sha256 |
| Windows | certutil -hashfile erya-*.tar.gz SHA256 |
The value must match the one in the .sha256 file. Then put the executable in any directory on your PATH:
| System | Usual location |
|---|---|
| macOS / Linux (just you) | ~/.local/bin or ~/bin |
| macOS / Linux (everyone) | /usr/local/bin (needs sudo) |
| Windows | Create C:\Tools and add it to Environment Variables → Path |
Executables downloaded from the internet carry a quarantine attribute, and macOS refuses to open them (“cannot be verified”). Clear it:
xattr -d com.apple.quarantine ~/.local/bin/erya
Or open System Settings → Privacy & Security and click “Open Anyway” once. This applies to every unsigned program, not to Erya specifically.
Installing from source
Needs Rust 1.85 or newer.
Check your toolchain with rustc --version and install it with rustup if needed. Then, in the project directory:
| Command | What it does |
|---|---|
| cargo run --release -- [file] | Builds and runs once without installing. Only what follows -- reaches Erya. |
| cargo install --path . | Builds and installs erya into Cargo's bin directory (usually ~/.cargo/bin). |
| erya [file] | How you run it afterwards. |
cargo run --release report.txt fails, because Cargo takes the filename as its own argument. Write cargo run --release -- report.txt — the two dashes tell Cargo that the rest belongs to the program.
Starting with or without a filename
Zero, one, or many files.
| Command | Result |
|---|---|
| erya | Opens one blank, untitled document. The first save asks for a name. |
| erya report.txt | Opens that file. A file that does not exist is not an error: you get a blank document, and the file is created on the first save. |
| erya a.txt b.txt c.txt | Three tabs, starting on the first. |
| erya -- -odd-name.txt | Everything after -- is a filename, never an option. |
| erya some-directory | Fails with “some-directory is a directory, not a text file”. To browse, start Erya and press Ctrl+O (see 2.1.2). |
Erya resolves a symlink to its target before opening, and saves back to the target rather than replacing the link with a regular file. Paths like ~/.zshrc, which are often links, behave the way you would expect.
Command-line options
Five of them. Each either prints something and exits, or swaps in a different config.
| Option | What it does |
|---|---|
| -h, --help | Prints help and exits: usage, options, environment variables, common keys — in your interface language. |
| -V, --version | Prints the version and exits, e.g. erya 1.0.0. |
| --languages | Lists the languages actually found in the translation directory, one per line as “codeTabname”. |
| --keymap <file> | Uses that key profile for this run (see 4.1.5). Without a path it fails outright. |
| --print-default-keymap | Prints the complete default profile to standard output — usually redirected into your own file. |
Common uses:
- erya --print-default-keymap > keymap.toml — a starting file with every action name in it.
- erya --keymap keymap.toml report.txt — open a file with your edited profile.
- erya --languages — check what to put in ERYA_LANG.
Any argument that starts with - and is not in the table above produces “erya: Unsupported option: -x” and a failure exit — it is not ignored. If a filename legitimately starts with a dash, put -- in front of it.
Four environment variables
All optional; Erya runs with none of them set.
| Variable | What it controls | See |
|---|---|---|
| ERYA_LANG | Interface language code, e.g. en, ja, zh-TW, zh-CN. When unset, LC_ALL, LC_MESSAGES, and LANG are consulted in that order. | 4.2.4 |
| ERYA_LOCALES_DIR | Translation directory; defaults to locales/. Point it at your own translations. | 4.2.5 |
| ERYA_KEYMAP | Key profile path — the same as passing --keymap every time. | 4.1.7 |
| ERYA_KEYMAPS_DIR | Which directory system settings (F2) lists profiles from; defaults to keymap/. | 4.1.3 |
For a single run, put it in front of the command:
- ERYA_LANG=ja erya report.txt — Japanese interface this once.
- ERYA_KEYMAP=~/my.toml erya — your own profile this once.
To make it permanent, add it to ~/.zshrc or ~/.bashrc (on Windows, to your user environment variables).
What the terminal must provide
Two hard requirements: a real terminal, and enough room.
- An interactive terminal. Both standard input and standard output must be TTYs. Piping or redirecting Erya fails immediately with “Erya must run in an interactive terminal”. cat a.txt | erya and erya > out.txt are both refused — it is an editor, not a filter.
- At least 24 columns by 6 rows. Below that the screen becomes a single yellow line, “Terminal is too small; enlarge it to continue”, and restores itself when you resize — nothing you were editing is lost. In practice give it 80×24 or more; 32 bytes per row in the hexadecimal view needs 144 columns (see 3.3.3).
- Bracketed paste, ideally. Almost every current terminal supports it. With it, pasting a block of text arrives as one paste rather than a storm of keystrokes. Erya enables it on start and disables it on exit.
Erya uses the terminal's alternate screen, so on exit your previous screen, cursor, and modes are restored and no editing session is left in your scrollback. The restore also runs when the program ends abnormally.
When it will not start
Match the message; the full troubleshooting chapter is 4.3.
| Message | Cause and fix |
|---|---|
| command not found: erya | Not on PATH. Try the full path, e.g. ~/.local/bin/erya; if that works, it is a PATH problem (1.2.3). |
| Permission denied | Not executable: chmod +x erya. |
| macOS: cannot verify the developer | Quarantine attribute: xattr -d com.apple.quarantine erya (1.2.3). |
| cannot execute binary file | Wrong architecture. Check with uname -m (1.2.2). |
| Must run in an interactive terminal | A pipe or redirection. Run it directly in the terminal (1.2.8). |
| Terminal is too small | Below 24×6. Enlarge the window (1.2.8). |
| Unsupported option: … | A typo, or a filename starting with a dash. Use -- (1.2.6). |
| … is a directory, not a text file | You passed a directory. Pass a file, or press Ctrl+O after starting (1.2.5). |
| Could not load key bindings; using defaults: … | Not an error — the program runs. The profile has a syntax problem or a conflict, so Erya fell back to the complete defaults and says why (4.1.8). |