Why the default is “terminal safe”
Because terminals do not deliver every combination you press.
The built-in default profile is called Erya Terminal Safe. It deliberately avoids three families of combination that fail in many environments:
| Avoided | Why |
|---|---|
| Ctrl + function keys | macOS reserves these for the system (Spaces, Mission Control); the program never sees them. |
| Combinations relying on Alt / Option | Option types special characters on macOS, and many terminals need configuring before they send it as Meta. |
| Modified arrow keys (Alt+Shift+← and friends) | A good number of terminals do not report them at all. |
The price is that sixteen advanced actions have no default key: eight for phrases and macros (see 2.4.8), four block shifts and one block fill (see 2.2.6), two for paragraph reflow (see 3.1.8), and “show cursor position”, which the status bar already covers. The features are all present; they just need a key. The full list is in 4.4.6.
The complete 1.0 bindings survive as Erya Classic, and one press of F2 switches back. If your terminal does report modified arrows and Alt combinations — GNOME Terminal or Windows Terminal usually do — Classic is the more comfortable set.
The twelve bundled profiles
All in the keymap/ directory, all selectable as they are.
| File | Who it is for |
|---|---|
| erya-terminal-safe.toml | The default. Works everywhere; the safest choice across platforms. |
| erya-classic.toml | Anyone wanting the complete bindings, phrases, macros, and block shifts included. |
| nano.toml | People coming from nano. |
| vim.toml | People who want vim's keys (not modal editing — only the bindings). |
| emacs.toml | People coming from emacs. |
| macos.toml | Anyone who prefers macOS application conventions. |
| vscode.toml / vscode-macos.toml | People coming from VS Code. |
| visual-studio.toml / visual-studio-macos.toml | People coming from Visual Studio. |
| intellij-idea-classic.toml | People coming from IntelliJ IDEA. |
| eclipse.toml | People coming from Eclipse. |
Where the default and Classic differ most
| Action | Terminal Safe | Erya Classic |
|---|---|---|
| Open file | Ctrl+O | Alt+O |
| Save As | F12 | Ctrl+O |
| Replace | Ctrl+R | Ctrl+H |
| Redo | Ctrl+Y | Ctrl+R |
| Delete line | Ctrl+D | Ctrl+Y |
| Copy | Ctrl+C | Ctrl+Insert |
| Close tab | F11 | Ctrl+F4 |
| Previous / next tab | F9 / F10 | Ctrl+Shift+Tab / Ctrl+Tab |
| Hexadecimal view | Ctrl+P | Alt+H |
| Block selection | Ctrl+B | Alt+B |
| Format document | Ctrl+T | Ctrl+Shift+F |
In the default, Ctrl+Y is redo; in Classic it deletes a line, and Ctrl+R swaps the other way. This is the pair people press by mistake after switching — glance at the hint bar first (see 1.3.3).
Switching profiles in system settings
The simplest route: no files involved.
- Press F2 for system settings.
- ↑ ↓ to the key-bindings row (the selected row is highlighted and marked ▶).
- ← → to change profile. The list is read from the keymap/ directory.
- Enter to apply. “Applied settings: Erya Classic / English”, and it takes effect in every tab immediately.
- Esc to cancel and change nothing.
Then Erya cannot find the keymap/ directory. Point ERYA_KEYMAPS_DIR at wherever it is (see 1.2.7) — the usual cause is unpacking only the executable from a release archive.
The keymap editor
Change bindings inside Erya, then save them as your own TOML.
| Key | What it does |
|---|---|
| ↑ ↓ | Choose an action. Description on the left, current keys on the right (blank means unbound). |
| Enter | Edit this action's keys. The input is pre-filled; separate several keys with commas. |
| Delete | Disable it (the same as leaving it blank): “Disabled shortcuts for the selected action”. |
| S | Save the whole profile as a new TOML file. |
| Esc | Back to system settings. |
- Keys that cannot be parsed, or that clash with another action, give “Could not update keymap: …” and nothing changes.
- Saving asks for a filename and confirms with “Saved keymap as …”.
- Save As never overwrites an existing file. An existing name fails rather than quietly replacing someone else's profile.
Two options: save it into the keymap/ directory so F2 can list it, or put it at the platform's default path (see 4.1.7) so Erya loads it on every start.
What the file looks like
A name and a [bindings] section.
Start from a file that lists every action:
erya --print-default-keymap > keymap.toml
| Example |
|---|
|
name = "My profile" [bindings] save = "Alt+S" quit = "Ctrl+X" search = ["Ctrl+W", "Ctrl+F"] toggle_rectangular_selection = "Alt+M" redo = [] |
- An action can have several keys: write an array.
- An empty array [] disables the action.
- Anything you leave out keeps its default. To change two keys, the file needs only those two lines.
- name is what appears in system settings and in row 1 of the keymap editor.
- The complete list of action names is in 4.4, or in the output of --print-default-keymap.
How to write key names
Join modifiers with +; case does not matter.
| Category | Accepted names |
|---|---|
| Modifiers | Ctrl, Alt, Shift, Super, Hyper, Meta |
| Ordinary characters | A–Z, 0–9, punctuation |
| Function keys | F1 to F24 |
| Navigation and editing | Left, Right, Up, Down, Home, End, PageUp, PageDown, Insert, Delete, Backspace, Tab, Enter, Esc |
Examples: "Ctrl+S", "Alt+Shift+Right", "F12", "ctrl+shift+f" (case-insensitive).
Plain F1 is reserved for keyboard help, and putting it in a config file is an error (see 1.3.8). It is the deliberate escape hatch: whatever a profile does to the rest, one key still lists everything.
Where the file has to live
Three ways to point at one, highest priority first.
- --keymap <file> — this run only, and it wins.
- The ERYA_KEYMAP environment variable — used when there is no --keymap.
- The platform default path — consulted when neither of the above is set:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Erya/keymap.toml |
| Linux | $XDG_CONFIG_HOME/erya/keymap.toml, or ~/.config/erya/keymap.toml when XDG is unset |
| Windows | %APPDATA%\Erya\keymap.toml |
Erya does not create one. If it is missing, the built-in defaults are used with no warning at all. A path you named explicitly with --keymap or ERYA_KEYMAP does produce a message when it cannot be read — because you said you wanted it.
Conflicts and the fallback
A broken profile does not stop the program; it just is not used.
- Two actions on one key — a conflict, because Erya cannot decide which to run.
- A misspelled key name or invalid TOML — a parse failure.
- Plain F1 bound to an action — reserved, and refused.
In each case Erya falls back to the complete default profile — not “ignore the bad line” — and explains why in the message row at startup. The program still runs.
Look at the hint bar on row 2 (it shows real keys), press F1 for the full list, or press F2 and read the profile name. All three tell you the truth.
Common problems
Seven situations when changing keys.
| Symptom | Cause and fix |
|---|---|
| You edited the file and nothing changed | It is not where Erya looks (4.1.7), or it was rejected and the defaults took over (4.1.8). Read the startup message. |
| “Could not load key bindings” at startup | A conflict or a syntax error; the reason follows the colon (4.1.8). |
| F2 lists no profiles | The keymap/ directory was not found. Set ERYA_KEYMAPS_DIR (4.1.3). |
| An Alt binding does nothing | The terminal is not sending Option/Alt as Meta. Bind something else, or enable it in the terminal (4.1.1). |
| Binding F1 is refused | F1 is reserved (4.1.6). |
| Save As fails | The filename exists. Erya never overwrites; choose another (4.1.4). |
| After switching, undo deletes a line | Ctrl+Y means different things in the two profiles (4.1.2). |