Skip to content

Usage

Jump to bottom
mike-ward edited this page Aug 7, 2026 · 3 revisions

Usage

This page covers day-to-day use of a go-term terminal. Falcon implements all of it, and any other term/workspace embedder does too. Key names are the macOS and Linux defaults. On Windows, Cmd becomes Ctrl+Shift.

Cmd+/ opens the in-app help overlay. It is generated from the live binding table, so it is always accurate for your config.

Tabs and panes

Chord Action
Cmd+D / Cmd+Shift+D Split vertically / horizontally
Cmd+[ / Cmd+] Previous / next pane
Cmd+Ctrl+←↑↓→ Resize the split
Cmd+T / Cmd+Shift+W / Cmd+Ctrl+W New tab / close pane / close tab
Cmd+1…Cmd+9, Cmd+Shift+[ / ] Select tab, previous / next tab

New tabs and splits inherit the focused pane's working directory. That needs the OSC 7 report the shell integration hooks emit. See below.

Copy and paste

Chord Action
Cmd+C / Cmd+V Copy / paste (Ctrl+Shift+C/V also)
Cmd+Shift+U / Cmd+Shift+Y Link hints: open / copy the labelled link
Cmd+Shift+Space Copy mode

Releasing a mouse selection copies it. There is no separate copy step for the mouse. On X11 the selection is also published as PRIMARY, the buffer middle click pastes. It is independent of the clipboard. Cmd+C and a mouse selection can hold two different values at once.

term.hints labels every link in the pane with a letter. Press the letter to open the link. term.hints-copy copies the URL instead. Both OSC 8 hyperlinks and plain http/https/mailto text are labelled, and the OSC 8 destination wins where a link is both. Only those three schemes are ever opened. A hostile destination cannot invoke an arbitrary handler.

Find

Cmd+F opens the search bar. Ctrl+R toggles regex, Enter and Shift+Enter move between matches. The bar stays open while you edit, and the pane scrolls to each match.

Copy mode

Cmd+Shift+Space enters copy mode: a vim-keyed state for scrolling the buffer and selecting text without a mouse. While it is active, no key reaches the shell, and incoming output freezes so the text you select cannot scroll away. A click anywhere leaves the mode.

Action Default Does
Exit Escape / q Leave copy mode
Left / Down / Up / Right h / j / k / l Move one cell
Word forward / back w / b Move by word
Line start / end 0 / $ Move to first column / last non-blank cell
Top / bottom g / G Move to oldest scrollback row / newest row
Half page Ctrl+U / Ctrl+D Move half a screen
Page PageUp / PageDown (also Ctrl+B / Ctrl+F) Move one screen
Select char / line v / V Start or cancel a selection
Yank y / Enter Copy the selection and exit
Search forward / back / / ? Open the search bar
Next / previous match n / N Move between matches
Previous / next prompt mark [ / ] Move between shell prompts

With no selection yet, y copies the single cell under the cursor. Pressing v or V a second time cancels the selection without leaving the mode. In the search bar, Enter moves the cursor onto the match and closes the bar. Shift+Enter does the same backwards. Escape closes the bar and stays in copy mode.

The $ and ? defaults are US-layout Shift+4 and Shift+/. On another layout, rebind them to whatever your keyboard actually produces.

Themes

Cmd+Shift+T opens the theme browser: a searchable list of every theme the embedder registered, with a live preview. Falcon registers the built-in Default plus 602 bundled themes. Type to filter, Up/Down to move, Enter to apply. The names are also valid for the theme key in the config file. See Configuration.

A light theme switches falcon's window chrome to light. Children that follow the terminal, like neovim and delta, re-theme themselves along with it.

Command palette

Cmd+Shift+P opens a searchable list of everything you can invoke. It spans both registries: the workspace.* commands and the term.* actions of the focused pane. Type to filter, Up/Down to move, Enter to run, Escape to clear the filter and then to close.

Actions you have unbound are not listed: the palette invokes an action by way of its chord, so an action with no chord has no way to run. The wheel scrolls the list without moving the selection, so a nudged mouse cannot retarget what Enter runs.

Broadcast input

Cmd+Shift+I mirrors what you type into every live pane in the active tab. While it is on, the split dividers turn amber and a broadcast badge sits at the bottom of the window. Typed keys and pastes are mirrored. Mouse reporting, selection, copy, and scrolling stay per-pane. Broadcast never persists: a restored workspace starts with it off.

Selection and mouse

Gesture Effect
Drag Select by character
Double click Select the word under the pointer. Drag to extend word by word
Triple click Select the whole logical line. Drag to extend line by line
Alt+drag Rectangular selection
Shift+click Extend the selection to the click point
Middle click Paste, when middle-click-paste is on
Cmd/Ctrl+click Open the URL under the pointer

A word is a run of non-blank characters with no punctuation class. Double-clicking grabs a whole path, URL, or --flag=value rather than stopping at every / or -. A logical line follows soft wraps, so triple-clicking one row of a wrapped paragraph selects all of it. Clicking a fourth time returns to character selection.

middle-click-paste defaults on for Linux, which has PRIMARY and the muscle memory that goes with it, and off for macOS and Windows. Where there is no PRIMARY, the gesture pastes the clipboard instead. A child that enabled mouse reporting always receives the middle button itself.

One wheel notch scrolls three rows. This matches xterm, kitty, and Windows Terminal. On the alternate screen, where pagers like less and man never enable mouse reporting, the wheel sends Up/Down keys instead, one per row of scroll distance. Full-screen applications that do report the mouse, like vim with mouse=a, receive real wheel events unchanged.

Shell integration

Prompt jumping, failure jumping, whole-output selection, and the long-command notification need your shell to mark where commands begin and end. The shell prints OSC 133 marks around each command. Until the hooks are installed, these do nothing:

  • Cmd+Up / Cmd+Down — jump to the previous / next prompt
  • Cmd+Shift+E — jump to the last failed command
  • Cmd+Shift+O — select a command's whole output
  • Failure ticks in the scrollbar
  • notify-after

Open a new pane in the current directory also depends on the OSC 7 report the same hooks emit.

Install the hooks

Add this line to your shell's rc file. It points at this repository's copy of the script:

# ~/.bashrc
source /path/to/go-term/scripts/shell-integration/goterm.bash
# ~/.zshrc
source /path/to/go-term/scripts/shell-integration/goterm.zsh
# ~/.config/fish/config.fish
source /path/to/go-term/scripts/shell-integration/goterm.fish

Then start a new shell.

The scripts are safe to source twice, and they append to any precmd/preexec chain you already have rather than replacing it. They emit nothing that other terminals mind. iTerm2, kitty, and WezTerm read the same marks, so one rc file works everywhere.

Two notes:

  • fish 4.0 and newer need nothing. They emit the whole set natively. The fish script exists only for fish 3.x.
  • bash can only preserve a DEBUG trap it can see. If you set your own trap … DEBUG, load bash-preexec before this script. It is detected and used, and then nothing fights over the trap.

Failure ticks and output selection

Cmd+Shift+E scrolls to the most recent command that exited non-zero, and each failure gets a red tick in the scrollbar track. Repeated presses walk back through older failures and then wrap to the newest. A command whose shell reported no exit status never counts as a failure.

Cmd+Shift+O selects exactly the output region of the command under the cursor and enters copy mode with that selection live, so y or Cmd+C copies it. On a fresh prompt it selects the previous command's output, which is the usual case right after a command finishes.

Long-command notifications

Set notify-after in the config file, and a desktop notification fires when a command that ran at least that long finishes while you look somewhere else. A command that finishes in the pane you watch never notifies, because you saw it happen.

[general]
notify-after = 30

The notification names the command and reports the duration, plus the exit status when the command failed.

Tab activity indicators

A tab you are not looking at shows a marker to the left of its title:

Marker Meaning
● The pane produced output
○ It produced output, then went quiet for 10 seconds
! The pane rang the bell

Switching to the tab clears the marker. These need no shell integration. They follow raw output, not marks.

Session recording and replay

Record a session to a .gtr file and play it back through the emulator itself. Recordings store the PTY's bytes verbatim, so malformed output survives the round trip. Keystrokes are captured only when explicitly enabled, and falcon leaves them off.

Cmd+Shift+R toggles recording on the focused pane. Recordings land in the recordings subdirectory of the go-term config directory. The gotermrec CLI inspects and converts them:

go run ./term/gotermrec info   session.gtr
go run ./term/gotermrec play   session.gtr
go run ./term/gotermrec export session.gtr -cast session.cast

info shows geometry, duration, and frame counts. play replays with timing in any terminal. export writes asciicast v2.

Play a recording in falcon:

falcon --replay session.gtr

Space pauses, +/- change speed, . steps, and 0 restarts. --replay is a viewer path: one pane, no tabs, no shell, no workspace persistence.

This is the preferred way to file a rendering bug: a recording reproduces the problem instead of describing it.

Font zoom

Cmd+= / Cmd+- / Cmd+0 zoom the font in, out, and reset. The zoom is an absolute point size on top of the configured size.

PageUp and the alternate screen

While a full-screen app owns the alternate screen, plain PageUp and PageDown pass through to the app. Only Shift+PageUp and Shift+PageDown scroll go-term's scrollback. That is the "hold Shift to talk to the terminal, not the app" idiom.

If you rebind the two scroll actions to a chord without Shift, they do not reach scrollback while the alternate screen is active. term.scroll-top and term.scroll-bottom have no such gate and rebind freely.

File transfers

OSC 1337 File= transfers are saved to ~/Downloads in falcon. This matches iTerm2. Transfers are opt-in per embedder, so this is falcon's policy, not the library's. They are disabled entirely when the home directory cannot be resolved. The DownloadDir field in term.Cfg or workspace.Cfg changes the destination.

Clone this wiki locally