¶Troubleshooting

¶A tool works in another terminal but not in eterm

Launched from the Dock, an application inherits launchd's PATH — four system directories, and nothing you installed. Open cmd-, → Shell: it lists every directory on PATH marked inherited, added or missing, and which known tools are reachable. Add what is missing to shell.path.

¶Folding and prompt jumping do nothing

They need shell integration. Without it there are no marks, so there are no blocks.

zsh gets it without being asked, so a zsh session that is not reporting means something has taken ZDOTDIR back: a [shell.env] entry that sets it, an rc file that sets it to somewhere with no .zshrc in it, or setopt norcs somewhere in the chain. cmd-, → Shell says which of the two states it thinks it is in. bash needs the line, and the strip above the footer offers to add it after two returns from a shell that has said nothing.

On a remote host the integration has to be installed there too, in an rc file: ZDOTDIR does not travel over ssh.

¶Backspace eats half of æ, ø or å

The shell is working in bytes rather than characters, which is what happens without a locale: æøå is three characters and six bytes, and a shell with no LANG counts six. Run locale — if it says LANG= and nothing else, the session started without one.

eterm sets LANG itself from 0.8.2 onwards. Before that, or if something in your login files unsets it, put one in [shell.env]:

[shell.env]
LANG = "nb_NO.UTF-8"

The drawing was never the problem: eterm renders æøå, combining marks and emoji correctly whatever the locale says.

¶The update strip says it could not install

The rest of the line says why, and Download opens the page for doing it by hand. Started from a build means this eterm is not an installed application and there is nothing to replace. Permission denied means the account cannot write to the folder eterm is in; ~/Applications avoids that. Signed, but not by eterm's developer means what is at the download address is not an eterm release, and should not be installed by hand either. See Updates.

¶The licence is not accepted

The status row under Licence says which of three things is wrong. Not a licence: the text is not the shape of one — it begins ETERM- and is a single line, so a line break in the middle from an email client is the usual cause. The signature does not match: a character went missing or changed in the paste; copy it again from the shop. Expired: it has a date and the date has passed; perpetual licences have none. See Licence.

¶The review window says there is nothing to review

Three things say that, and they say it differently:

• "this is not a GitHub checkout" — the directory the session is in has no .git above it, or its origin remote is not GitHub. Only origin counts; see Review.
• "no GitHub token" — cmd-, → Review → Set key….
• "nothing open to review here" — the repository is right and the token works; there is no open pull request. A branch you push straight to main never has one.

¶The AI key will not save

Two things have caused this:

• The keychain refused. macOS grants access per code signature, so the first read prompts, and a rebuilt eterm asks again. Answer Always Allow. If the prompt was dismissed, the key row says so rather than saying "not set".
• The window was not listening. Fixed in 0.2.0: opening the settings window did not make it the window receiving keys.

¶AI mode runs one command and stops

Continuing needs the shell to report that a command has finished, which is OSC 133. Install shell integration from cmd-, → Shell, and on a remote host, install it there too.

¶Return will not run the command AI proposed

It was recognised as destructive, and the panel says which shape it matched. That is deliberate: cmd-shift-return runs it, cmd-return puts it on the input line to edit first. If the reason looks wrong, it is a pattern match on a string and it will sometimes be wrong — read the command and decide.

¶Folding does nothing

Before 0.3.0 it needed the cursor to be inside the block, which it never is after a command has finished. Update, or scroll into the output first.

¶Escape does not reach vim

Escape closes whatever is open on top — the command palette, the search bar, AI mode — and reaches the shell otherwise. If a program is not seeing it, something is open above the session; press escape once more.

¶Option key types the wrong thing

keys.option_as_meta decides. Off, the option key composes: ⌥U then A is ä. On, it sends ESC-prefixed keys for readline. It cannot do both.

¶Input method does not compose

Composition happens in the grid but not in the search or AI fields' neighbour — that is, it works everywhere text is typed. If it does not, check that printable keys are not being intercepted by an overlay: an overlay owns the keyboard while it is open.

¶Everything is slow

Run with ETERM_TRACE=1 and watch stderr. Every 120 frames it reports where the time went:

eterm: 480 frames · mean 0.15ms = metrics 0.01 + sync 0.00 + walk 0.11
       + shape 0.03 (lock 0.00) · 32 rows/frame · 20 runs/row

Anything above a millisecond deserves a look. The largest number ever seen here was a font lookup running once per frame, at 20ms.

¶The window is blank or the app will not start

Run it from a terminal to see stderr:

/Applications/eterm.app/Contents/MacOS/eterm

A shell that exits immediately closes its pane, and the last pane closes the window. If shell.program in the settings file points at something that is not there, that is what it looks like.