Terminal
The built-in terminal and your own terminal application: which shell runs and what the application adds to it, how its tabs are titled, how the Option keys and the wheel reach a program, and which terminal application opens for you.
Four are read as a shell starts — the shell, its integration, the lines it keeps and the clipboard — so a change to one counts from the next tab you open, and every shell running keeps what it started with. The rest count as soon as they are set — on the settings screen, when you choose OK or Apply.
They are on the settings screen — Options › Settings…, or Settings… in the application menu, ⌘, — under Terminal, and in settings.json.
Your own terminal externalTerminal
The terminal that opens where a pane is, by its application name. automatic finds one.
Default: automatic
Which terminal ⌥⌘T opens at the active pane’s folder, and which comes first among the command line’s Run in rows.
| Value | Opens |
|---|---|
| automatic | The first of these that is installed: iTerm2, Terminal, Ghostty, kitty, Warp |
An application’s name, such as Ghostty |
That terminal, wherever it is installed. Capitals do not matter |
- A name that is not installed opens the one automatic would, rather than nothing.
- Only iTerm2 and Terminal can run a line typed on the command line. The others take a program to run rather than a line for their own shell, so they are only ever opened at a folder.
Commands open a new externalTerminalOpens
Whether a command from the command line runs in a new tab or a new window. Terminal always opens a window.
Default: tab · tab, window
| Value | A command from the command line’s Run in rows runs in |
|---|---|
| tab | A new tab in iTerm2’s front window |
| window | A new window |
- Terminal always opens a new window, whatever this says: its scripting cannot make a tab.
- A terminal that was not running opens with a window of its own, and the command runs in that.
Built-in terminal shell terminalShell
The shell the built-in terminal runs, by full path or by name. automatic is your login shell.
Default: automatic
| Value | Runs |
|---|---|
| automatic | Your login shell |
A name, such as fish |
That shell, looked for on the path and in /opt/homebrew/bin, /usr/local/bin, /bin and /usr/bin |
| A full path | That program |
- A shell that cannot be found runs your login shell instead.
- Whichever it is, it runs as a login shell. zsh, bash and fish get the integration; any other shell runs without it.
Shell reports where it is terminalIntegration
Start the shell with the scripts that report its directory and each command.
Default: on · on or off
On, zsh, bash and fish are started with scripts that report the folder they are in and where each command starts and ends — which most of the terminal stands on. Your own start-up files are read as usual, and nothing is written into them.
Off, they start as plain shells, and what needs the reports is not there:
- Taking the command line does not move the shell to the pane’s folder, and a shell beside a pane does not follow it, nor it the shell.
- A command from the command line brings up the terminal once the delay in Terminal after, in ms has passed, and leaves it up: nothing says when it ended.
- No stepping through commands, no command history list, and no last command’s output.
- Closing a tab, or quitting, asks first whenever a shell is open, since no shell can say it is idle.
The full list is in what needs it.
Lines kept above screen terminalScrollback
How many lines scrolled off the top of the built-in terminal it keeps.
Default: 10000 · 0 to 1000000
They are what the wheel scrolls back through, and what ⇧⌘F3 shows in the viewer with the screen. 0 keeps none.
- A program on a screen of its own — an editor,
less— keeps nothing above it, whatever this says. - A command whose start has gone from what is kept can no longer be stepped to, nor shown with ⌘F3.
Programs may use the clipboard terminalClipboardWrite
Whether a program in the built-in terminal may put text on the clipboard.
Default: off · on or off
Off, as shipped, nothing a program prints can put text on your clipboard — a command placed there by a program’s output is one you might paste and run later without reading it.
Whatever this says, a program in the terminal is never told what is already on the clipboard.
Tabs are titled by terminalTabTitle
What a terminal tab shows where it has not been named: its folder, or the command running in it.
Default: folder · folder, command
| Value | A tab is titled by |
|---|---|
| folder | The name of its shell’s folder — ~ for your home |
| command | While a command runs, the command. Otherwise its folder |
- A name you give a tab with ⇧⌘I replaces the title either way.
- Both come from the shell’s integration. Without it, a shell that does not say where it is gives its tab the shell’s own name.
Left Option key terminalLeftOption
normal types what the keyboard layout puts there. meta sends the program an escape first, for Alt bindings.
Default: normal · normal, meta
| Value | The left ⌥ with a key |
|---|---|
| normal | Types what the keyboard layout puts there — ©, ∑, or an accent for the next letter |
| meta | Sends the program Esc and then the key’s own character, as the shells’ word motion, fzf’s ⌥C and a program’s Alt bindings expect |
- Setting only one side to meta keeps the other for typing characters.
- ⌥ with an arrow or a function key is sent with Alt held, either way.
- On the command line, ⌥↑ and ⌥↓ on a normal side step through the shell’s own history. On a meta side, they go to the shell as they are.
Right Option key terminalRightOption
normal types what the keyboard layout puts there. meta sends the program an escape first, for Alt bindings.
Default: normal · normal, meta
As Left Option key, for the ⌥ key on the right. An ⌥ already held when the window came to the front counts as meta only where both sides are set to it.
Shell follows the pane terminalFollowsPane
Whether a terminal in a pane's place moves its idle shell to where the pane beside it goes.
Default: on · on or off
Only for a terminal standing beside a pane. On, its shell moves to where the pane goes, once the pane has stayed in one folder for half a second, and the row over the shell says followed the pane. Off, the shell stays where it is.
- The pane still follows the shell either way.
- A shell running a command follows at its next prompt. One you are typing at is never moved.
- Nothing is typed at the shell to move it. It needs the shell’s integration.
Wheel scrolls in less and man terminalAlternateScroll
Whether the wheel sends up and down arrows to a full-screen program that has not asked for the mouse.
Default: on · on or off
For a program that fills the screen without asking for the mouse — less, man. On, the wheel sends
it ↑ and ↓, a row a notch, which scrolls what it shows. Off, the wheel does nothing there.
- A program that asked for the mouse gets the wheel itself, either way.
- At a prompt, the wheel scrolls back through what has scrolled off, either way.