Terminal

Iruka's built-in terminal is an xterm-compatible emulator powered by SwiftTerm. It supports 256 colours, true colour, mouse reporting, and most terminal escape sequences used by modern CLI tools.

When Sync pauses

Iruka stops sending cd while the shell is busy with something that might be reading your keystrokes — an editor, a pager, a REPL, a long build. Sending a cd into vim would type it into your document.

It keeps following through anything that is itself a shell, or that hands straight to one:

sh · bash · zsh · fish · dash · ksh · tcsh · csh · nu · xonsh · elvish · pwsh — and su · sudo · doas · login · runuser · nix-shell · direnv · script

So su-ing to another user no longer stops the terminal following you, and Sync resumes by itself once a program that did pause it exits.

Multiplexers are excluded by default. tmux, screen and zellij run their panes under a separate server process, so Iruka cannot see what is inside a pane — following one risks typing a cd into an editor rather than a prompt. If your panes are usually at a shell prompt, turn off Settings → Terminal → Pause Sync inside tmux, screen and zellij and it will follow them too.

ssh you typed yourself is deliberately excluded. The paths Iruka would send are local ones, which don't exist on the other machine. Sync resumes when you exit. The exception is an SSH session Iruka opened for a mounted volume, where it knows how local paths map to the server's — see SSH & SCP.

Show / Hide

Press F4 to toggle the terminal pane. The terminal remains alive in the background when hidden — running processes are not interrupted.

Focus

Press ⌘ ⌥ T to move focus between the file browser and the terminal without leaving the keyboard. Press it again to return to the file browser. If the terminal is hidden, ⌘ ⌥ T shows it first.

Sessions (Tabs)

Each Iruka tab has its own independent terminal session.

• New tab — ⌘ T or the + button in the tab bar
• Close tab — ⌘ W
• Switch tabs — ⌘ { / ⌘ } or ⌃ Tab / ⌃ ⇧ Tab

Shell

By default Iruka launches your system shell ($SHELL). Override it in Preferences → Terminal → Shell.

Supported shells:

| Shell | Notes | |---|---| | System Default | Whatever $SHELL resolves to | | zsh | Built into macOS | | bash | Built into macOS | | fish | Detected at /opt/homebrew/bin/fish or /usr/local/bin/fish | | PowerShell (pwsh) | Detected at /opt/homebrew/bin/pwsh or /usr/local/bin/pwsh — install via brew install powershell | | Custom path | Full path to any shell executable |

Shell applies to new tabs only. Existing sessions keep the shell they started with.

On macOS, PowerShell 7 (pwsh) via Homebrew is recommended over Windows PowerShell (not available on Mac).

Navigation Sync

When Sync is enabled (the Sync button in the terminal header), navigating in the file browser automatically changes the terminal's working directory.

The command sent depends on the tab's shell:

| Shell | Command sent | |---|---| | POSIX (zsh, bash, fish, system default, custom) | cd '/path/to/folder' | | PowerShell (pwsh) | Set-Location -LiteralPath '/path/to/folder' |

Single quotes in the path are escaped correctly for each shell (POSIX: '\'', PowerShell: '').

You can also trigger a one-time sync with the ↓→ button in the terminal header, or read the terminal's current directory back into the file browser with the ↑← button.

When Sync pauses automatically

So it never interrupts a command you're running, Sync watches for a foreground process in the shell. When it sees one it holds the cd and shows "Sync paused — terminal is busy"; once the command finishes, Sync resumes and jumps to your current folder.

Because a nested interactive shell also counts as a running process, starting one pauses Sync too — for example su - / sudo -i (switching user), ssh into a remote host, tmux / screen, or a REPL like python. Iruka can't distinguish these from a long-running command. Click Sync (or Re-enable in the banner) to resume following.

Note that following into a su - / sudo -i session is limited by design regardless: it starts in the other user's home directory, and that user may not have permission to enter the folder you're browsing — so a paused Sync is often the safer outcome there.

Note: git, SSH, and SCP commands injected into the terminal assume the standard Unix tools (git, ssh) are on the shell's PATH. This is typical on macOS for all supported shells.

Copy and Paste

• Copy — ⌘ C (when the terminal has focus)
• Paste — ⌘ V
• Right-click anywhere in the terminal for a Copy / Paste / Select All context menu

Fonts

Go to Preferences → Terminal to change the terminal font:

• System Monospaced (default) — maps to SF Mono, Apple's system monospaced font
• Any installed monospaced font on your Mac is listed and available

Ligatures (Experimental) — enables OpenType ligature features (liga and calt). Because Iruka renders each character cell individually, ligatures that require multiple cells to combine (e.g. =>, !=) may not display as expected in all cases. This setting is off by default; enable it if your chosen font supports ligatures and the results look good to you.

Themes

Iruka ships with a curated set of colour themes. Switch themes in Preferences → Terminal Themes. Changes take effect immediately in all open terminal windows.

Custom themes are not yet supported but are planned for a future release.

Scrollback

The terminal keeps the last 10,000 lines by default. Scroll with the trackpad or use ⌘ ↑ / ⌘ ↓ to jump to the top or bottom.