Xpecter user guide.

At a glance

Xpecter is a desktop terminal for people who spend the day on remote machines and network hardware. One window holds SSH sessions, local shells, serial consoles, Telnet and Mosh, saved Remote Desktop and VNC sessions, a code editor that works on local and remote files, an SFTP browser, and a set of network tools. It works the same way on Windows, macOS, and Linux.

Throughout this guide, Ctrl means Cmd on macOS. The app always shows the right key for your platform.

New since v3.4

Each feature below has its own write-up further down: what it does, how it works, and step-by-step use. Follow the link to jump there.

Installing and updating

Download the build for your platform from the Releases page. There is no account and no setup wizard. Xpecter opens on the Home tab.

Checking for updates

Xpecter can tell you when a newer release is out and fetch it for you.

How it works

Xpecter doesn't check in the background. When you ask, it looks up the latest release on GitHub and compares it with the version you're running. If yours is current, nothing changes. If a newer release exists, a banner appears with a Download button.

How to use it

1. Open Settings > About and click Check for updates….
2. If the banner appears, click Download.
3. On Windows, the installer downloads and runs; follow it through. On macOS and Linux, the archive is downloaded and revealed in your file manager. Quit Xpecter and replace the old app or binary with the new one.

Your sessions and settings live in a separate configuration folder (see Your configuration), so replacing the app doesn't touch them.

The window

Xpecter draws its own title bar. It holds the Terminal, Sessions, View, Tools, and Settings menus, a light/dark toggle, and the window controls. Every action in this guide is on one of those menus, on a right-click menu, or on a shortcut.

Tabs

Each tab holds one pane layout. The ⌂ Home tab is permanent and can't be closed. Every other tab shows an icon for what it holds, a status dot, and a close button. Drag tabs to reorder them. Turn on Show tab numbers in Settings to number them, which makes the jump shortcuts easier to use.

How it works

Xpecter keeps watching tabs you aren't looking at. A background tab shows a dot when new output arrives, and 🔔 when its terminal rings the bell (the BEL character, which many programs and shells send to get your attention). A bell in a background tab, or in any tab while the Xpecter window is behind other windows, also raises a system notification. That means a long job can tell you it's finished, for example make; printf '\a', even while you're working in another app.

How to use it

• Ctrl + Tab moves to the next tab and Ctrl + Shift + Tab to the previous one.
• Ctrl + 1 to Ctrl + 8 jump to that tab; Ctrl + 9 always jumps to the last tab.
• To stop the system notifications, turn off Notify when a background terminal rings its bell in Settings > Terminal. The 🔔 on the tab still appears.
• Closing a tab with a live session asks first. By default the app quits when the last tab closes; turn on Keep app open when last tab closes to be left on Home instead.

Split panes

A tab can be split into two panes side by side, two stacked, or a four-pane grid. Every pane is independent. It can hold an SSH session, a local shell, a serial console, a Remote Desktop or VNC card, or a text editor, so a configuration file can sit open beside the switch you're writing it for.

How to use it

1. Split the tab with View > Split Vertical (Ctrl + Shift + D), Split Horizontal (Ctrl + Shift + Enter), or 4-Pane Grid.
2. Fill the new pane with the ⊟ button beside the tab bar. It offers a duplicate of the current session, a new local shell, a new session from the picker, a text editor, or an empty split.
3. Drag the divider to resize the panes. Drag a pane by its header onto another pane to swap them.
4. Click a pane to give it the keyboard, or hold Alt and press an arrow key to move focus.
5. Ctrl + Shift + W closes the active pane.

Send input to all panes

Broadcast mode sends what you type in one pane to every terminal pane in the tab. It's for running the same command on several machines at once, such as a show version across four switches.

How it works

While broadcast is on, every keystroke and paste in the focused pane is copied to each terminal pane in the same tab. Editor panes and Remote Desktop or VNC cards are left out, and other tabs are never affected. Every pane header shows that broadcast is on, so it's hard to forget. Pastes and command snippets still go through the paste guard. You're asked once, and your answer applies to every pane the text reaches. If any of those panes carries a tag set to ask before pasting, it still asks.

Broadcast belongs to one tab. It's off in every new tab, and it switches itself off if the tab is no longer split.

How to use it

1. Split a tab and connect each pane to a machine. For example, open a 4-Pane Grid with one switch in each pane.
2. Turn broadcast on with View > Send Input to All Panes, or click the ⇶ button on any pane header.
3. Type in any pane. The same input appears in all of them.
4. Turn it off the same way when you want to work on one machine again.

Named layouts

A layout is a saved arrangement of tabs that you can reopen whenever you need it. Save a rack of switches as a four-pane grid once, and it comes back with every pane connecting again.

How it works

A layout records the open tabs, how each one is split, and what each pane holds: the saved session, local shell, serial console, editor, or Remote Desktop or VNC card. That's everything needed to start each session again. A layout never stores a password or terminal output. Reopening a layout starts each session just as if you'd opened it yourself, so SSH sessions that need a password ask for it. Layouts are part of your configuration, so they're included when you export it and restored when you import it on another machine.

How to use it

1. Arrange the tabs and panes the way you want them.
2. Choose Sessions > Save Tab Set as Layout… and give it a name.
3. To reopen it, choose Sessions > Open Layout…, or click its card in the Layouts section on Home.
4. Rename a layout with the ✎ on its Home card, or delete it with ✕.

Pick up where you left off

Xpecter remembers the tabs you had open when it last quit and offers them back at the next launch.

How it works

Xpecter records the tab set as you work, not only when you quit. At the next launch, Home offers to reopen it, or reopens it automatically if you've chosen that. These come back:

• Tabs and split panes, in the same arrangement
• Each editor's open folder and files
• Local shells and serial consoles
• Remote Desktop and VNC cards
• SSH sessions

SSH sessions reconnect on their own when they can authenticate without you: with a key, an agent, or a password saved in the OS keychain. A session that needs a password asks for it. If you cancel, the session waits in its pane until you press R to connect.

How to use it

• At launch, click Reopen on Home to bring the last tab set back.
• Tick Always reopen automatically to skip the offer in future.
• Choose Start fresh under Settings > Terminal > On launch to stop being asked altogether.

The sidebar

The sidebar has four collapsible sections: Sessions, Local shells, Folders (pinned editor folders), and Remote files (the SFTP browser). Drag its edge to resize it. Press Ctrl + Shift + B or click the « button to hide it.

The Home tab

Home is what you see at launch, and whenever no session is using the tab. It shows:

• Quick connect
• Pinned sessions
• Recent sessions, with how long ago each was opened
• Every saved session, grouped by folder
• Saved layouts and local shell chips
• The offer to reopen your last tabs
• A strip with the current bindings for the most common shortcuts

The status bar

A thin bar at the bottom shows short confirmations and errors, such as a file saved, a forward stopped, or how many sessions an import brought in. Each message fades after a moment.

Your first connection

1. Open the session picker: Sessions > New Session, the + New Session button on Home, or + in the sidebar's Sessions header.
2. Press 1 or click SSH. Enter the host and user, and choose Password or Key.
3. Click Connect. The first time you reach a host, Xpecter shows its key fingerprint. Check it against what the host's administrator gave you, then choose Trust and connect.
4. Once you're connected, Xpecter offers to save the session. A saved session stores the host, user, port, key path, and options. It never stores a password unless you've deliberately turned on keychain saving.

Quick connect

The box at the top of Home does two jobs. It searches your saved sessions by name, host, or tag, and it connects straight to an address you type in.

How to use it

• Type part of a session's name, host, or tag, move through the results with the arrow keys, and press Enter to connect.
• Type user@host, or user@host:port for a non-standard port, and press Enter to connect to a machine you haven't saved.

Session types

The session picker (Sessions > New Session) offers seven choices. Press the number or click the tile; Esc closes the picker.

SSH

The SSH form takes a host and user, a device kind, and password or key authentication. The device kind (VM or host, network switch, or firewall) only chooses the icon shown in the sidebar. If Caps Lock is on while you type a password, a warning appears under the field. The options below are under Advanced settings, both in the SSH form and in the Edit session dialog.

Keys and agents

• Key file. Browse to a private key and enter its passphrase if it has one. If the file's permissions let other users read it, Xpecter flags it and offers Use it anyway.
• Use SSH agent. Xpecter asks your running SSH agent to sign the login instead of reading a key file. It works with the OpenSSH agent on Windows, macOS, and Linux, and with PuTTY's Pageant on Windows. The private key never leaves the agent.
• Use Xpecter memory agent. After you unlock a key once, Xpecter keeps it unlocked in memory for the rest of this app run, so later connections don't ask for the passphrase again. Nothing from it is written to disk, and it's cleared when Xpecter quits.

Agent forwarding

Forward the agent to the host lets programs on the remote host use the keys on your machine without copying them there. Once it's on, a git pull from a private repository on the host authenticates with your local key, and so does an ssh from that host to a second machine behind it. Xpecter requests forwarding when the shell starts. If the host refuses (many servers disable it), a message on the terminal says so and the session carries on without it.

X11 forwarding

Enable X11 forwarding lets graphical programs started on the host, such as xclock or wireshark, open their windows on your screen. Xpecter proxies the X11 channels to your local display, so you need an X server running locally: native X on Linux, XQuartz on macOS, or VcXsrv or Xming on Windows.

Jump host

A jump host (or bastion) is a machine you have to pass through to reach the target. Enter it in OpenSSH ProxyJump form, [user@]host[:port], for example ops@bastion.example.com:2222. Xpecter connects to the jump host first, then opens a channel through it to the target, so the target never needs to be reachable from your machine. The jump host's key is checked against known_hosts exactly like the target's.

Terminal speed and compatibility

• Terminal speed sets the baud rate reported for the remote terminal. Most hosts ignore it, but console servers and serial-over-SSH bridges read it to set the speed of the serial line behind them.
• Legacy algorithms. If a host only offers old key exchange, cipher, or host key algorithms, Xpecter falls back to them automatically. Older network hardware connects without a compatibility switch.
• SSH keepalive (prevent idle disconnects) (on by default, in Settings > Terminal) sends a small message over idle sessions so firewalls and NAT devices don't drop them on a timeout.

Shell

A local shell on this machine. On Windows, this is PowerShell by default, and Command Prompt and PowerShell are also on the Tools menu. On macOS and Linux, it's your login shell.

How to use it

• Local shell profiles are named shells with a starting directory, such as "Website" opening in your project folder. Create one from Terminal > Manage Local Shell Profiles…, or with + in the sidebar's Local shells section. Profiles appear in the Terminal menu, the sidebar, and Home.
• New Local Shell in Directory… (Terminal menu) picks a folder and starts a shell there without saving a profile.
• On Windows, Explorer's right-click menu gains Open in Xpecter for folders and folder backgrounds. It opens a shell in that folder.

Serial

A console over a serial port, for switches, routers, and boards that are out of reach of the network. Enter the port name, such as COM3 on Windows, /dev/ttyUSB0 on Linux, or /dev/tty.usbserial-… on macOS, and a baud rate from 9600 to 115200. Serial sessions are saved, grouped, filtered, and logged like any other, and use the same terminal.

Console controls

A serial session has a bar between its header and the terminal for controlling the line itself:

The bar's settings apply to pasted text as well as typing, so a pasted configuration uses the same line endings you chose.

Telnet

Unencrypted, for legacy equipment that doesn't speak SSH. Enter the host and port (default 23). Xpecter runs your system's telnet client inside a local shell, so that client must be installed. On Windows, it's an optional feature you may need to turn on.

Mosh

Mosh is a remote shell that survives network changes: move from Wi-Fi to a cable, or put the laptop to sleep, and the session is still there. Choose Terminal > New Mosh Session… and enter user@host. Xpecter runs mosh in a local shell, so you keep Xpecter's tabs, resizing, logging, and highlighting. You need the mosh client on this machine, and mosh-server on the host with its UDP ports open (60000–61000 by default).

Remote Desktop

Enter the host, port, user, and an optional domain, then choose a display mode:

• Full screen.
• Resizable window. The remote desktop follows the window size as you drag it.
• Fixed resolution. The desktop is scaled to whatever size you give the window.

Console session (/admin) attaches to the server's console session instead of starting a new one.

How it works

Xpecter doesn't draw the desktop itself. It writes a .rdp file with everything filled in and starts the client your platform already has: Remote Desktop Connection on Windows, Windows App on macOS, and FreeRDP or Remmina on Linux. That client asks for the password; Xpecter never stores one.

A pane in Xpecter stands for the session and shows whether the client window is still open. From that pane:

• R opens the window again.
• D closes the window.
• Enter closes the pane.

VNC

Enter the host and port. VNC works the same way as Remote Desktop. It opens in your platform's viewer: Screen Sharing on macOS, or TigerVNC, RealVNC, TightVNC, UltraVNC, Remmina, or Vinagre elsewhere, whichever is installed. The viewer asks for the password, and a session card in the pane tracks it with the same R, D, and Enter actions.

Saved sessions and the sidebar

The Sessions section

The sidebar lists sessions in this order:

1. A ★ Pinned group
2. A Running group of sessions connected right now
3. Your folders
4. Ungrouped sessions

Each row has a status dot, the session's name, and a device icon; hover it to see the address. Clicking a session that's already connected switches to its tab instead of opening a second connection. Open another session on the right-click menu opens a second one deliberately.

Filter sessions… at the top of the section matches on name, host, serial port, and tags, and filters local shell profiles at the same time. While a filter is active, folders step aside and each row shows its address. Arrow keys move through the matches and Enter connects.

Right-click menu

• Pin to top, or Unpin
• Open another session
• Edit session
• Forget saved password (SSH, while keychain saving is on)
• Delete. It asks first, and also removes any password saved in the keychain for that session.

Folders and pinning

Create folders from Sessions > New Folder or the 📁 button. Folders can nest. Drag a session onto a folder to move it there. Right-click a folder to rename or delete it; deleting a folder moves its sessions out rather than deleting them. Pinned sessions sit at the top of the sidebar and lead Home, so the machines you use every day are one click away right after launch.

Tags, tag colours, and ask before pasting

Tags label sessions. A tag can also carry a colour, which marks every session wearing it, and can be set to ask before pasting, which adds a safety check to sessions where a stray paste would hurt.

Where to find it

Open Settings and find Colorize terminal output in the Terminal group. Tag colours is the second panel beneath it, after Custom highlight rules. Tags themselves are added to sessions in the Edit session dialog.

The Tag colours panel

Each coloured tag has one row:

Tags are listed in alphabetical order. Out of the box the panel holds six: prod and production in red with ask before pasting ticked, staging in orange, and dev, lab, and test in green. Below the list is a row for adding your own. Removing one of the six built-in tags is remembered, so it doesn't come back at the next launch.

How colours work

A session's tab, pane header, and sidebar row wear the colour of its first coloured tag, so a terminal on a production box is recognisable from across the room, even in a crowded split. Only coloured tags count. A session tagged core, prod, dc1 is red, because core has no colour and prod is the first tag that does. If a session has two coloured tags, the order you typed them in decides which colour wins, so put the most important one first. Tag names ignore case: PROD, Prod, and prod are the same tag, and names are stored in lower case. A tab holding a split takes the colour of the first pane whose session has a coloured tag. Colour changes show on open tabs and the sidebar straight away.

How ask before pasting works

In a session carrying a tag with ask before pasting ticked, Xpecter stops and asks before sending:

• Any paste containing a line break, meaning a paste that would press Enter and run something. That includes a single line copied together with its trailing newline.
• Any command snippet

The prompt names the tag and the session, so you know exactly where the text is about to go. It asks however the general Warn before pasting multiple lines setting is set, so turning that warning off never removes this check. Ordinary typing, and pastes with no line break in them, are never interrupted.

Unlike the colour, the check doesn't depend on tag order. A session asks if any of its tags has ask before pasting ticked, even one that isn't providing the colour. The prompt names the tag in capitals, for example PROD, together with the session.

How to use it

1. Tag your sessions. Right-click a session, choose Edit session, and type comma-separated tags under Advanced settings, for example prod, core. The sidebar filter and Quick connect both search tags.
2. Add a colour for a new tag. In Settings, type the tag's name in the tag box under the list. Click the swatch beside it to choose a colour, tick ask before pasting if sessions with this tag need protecting, and click Add or press Enter. Adding a name that's already in the list replaces its colour and setting.
3. Change an existing tag. Click its swatch to recolour it, or tick or untick its ask before pasting box.
4. Remove a tag's colour with the ✕ at the end of its row.
5. When the prompt appears in a protected session, check the session name it shows, then confirm to send the text or cancel to drop it.

The Edit session dialog

Right-click a session and choose Edit session. Basic settings has the name and the fields for the session's type. Advanced settings adds:

• The key path and agent options, including agent forwarding
• The device kind, jump host, and terminal speed
• Remote Desktop display options
• The folder and tags
• The port forwards the session starts with

Importing sessions

Three importers under Settings bring in sessions you already have elsewhere. Each one adds sessions alongside the ones you have, and reports in the status bar how many it imported.

• Import from MobaXterm… reads .mxtsessions and .ini exports and maps names, hosts, users, ports, and key paths. Passwords are skipped.
• Import from SSH config… reads an OpenSSH ~/.ssh/config and saves each concrete Host block as a session, carrying HostName, User, Port, IdentityFile, and ProxyJump. Blocks made only of wildcards, such as Host *, hold defaults rather than machines, so they're skipped.
• Import from PuTTY… (Windows) reads PuTTY's saved sessions straight from the registry. It brings in the host, port, user, agent settings, X11, an SSH proxy as the jump host, and serial sessions with their line and speed.

Saved passwords, in the OS keychain

This is the only setting that makes Xpecter keep a password at all, and it's off by default.

How it works

With Remember SSH passwords in the OS keychain turned on, a saved SSH session can keep its password in your operating system's credential store: Windows Credential Manager, macOS Keychain, or the Linux Secret Service. The password is never written to Xpecter's own files or included in an export. The next time you connect, it fills in automatically.

How to use it

1. Turn on Remember SSH passwords in the OS keychain in Settings > Security.
2. Connect to a saved SSH session with its password. It's stored in the keychain.
3. To forget one password, right-click the session and choose Forget saved password, or delete the session. To forget them all, turn the setting off.

When a session drops

If a session disconnects, times out, or fails, its pane stays where it is and shows a Session stopped panel, so the output isn't lost. Anything you type is held rather than sent into a dead connection.

• R reconnects to the same host.
• S saves the output that was on screen to a file.
• Enter closes the pane.

To end a session on purpose, use Terminal > Disconnect (Ctrl + Shift + X).

Session logging

Logging keeps a record of everything your sessions print. It's off until you choose a directory.

How it works

Once a directory is set, raw output from every SSH, local shell, and serial session is appended to a file named after the session. "Raw" means exactly what arrived, so logs can include the terminal's own control sequences as well as text.

How to use it

Open Settings > Session logging, click Choose…, and pick a directory. Click Disable session logging to turn it off again.

Working in the terminal

Output highlighting

Colorize terminal output (on by default) colours plain output the way an operator reads it, so you can see at a glance what matters. It highlights:

• Words that mean something worked, failed, or needs attention
• Interface names, in long and short forms (GigabitEthernet0/1 and Gi0/1)
• IPv4, IPv6, and MAC addresses, including prefix lengths
• %FACILITY-severity-MNEMONIC log tags
• URLs, and Windows and POSIX paths
• ISO-8601, syslog, and IOS timestamps
• Sizes, rates, percentages, and hex values

How it works

Highlighting is applied as output arrives. It works the same on Linux hosts, switches, PowerShell, Command Prompt, and serial consoles. Text that the far end already coloured is left exactly as sent, so coloured prompts, ls --color, pagers, and vim are never recoloured. The colours come from your terminal colour scheme, so they suit whichever theme you use.

Custom highlight rules

Add patterns of your own to the built-in highlighting, such as your site codes, a hostname scheme, or the alarm words your equipment uses.

Where to find it

Open Settings and find Colorize terminal output in the Terminal group. Custom highlight rules is the first panel beneath it. Until you add a rule, the panel says "No custom rules yet."

The panel

How it works

• Words match whole, ignoring case. Separate them with commas or spaces. CRIT, DOWN, c++ colours DOWN and down but not DOWNLOAD. A hyphen counts as part of a word, so fan does not light up inside fan-tray; add fan-tray as its own word if you want it. Each word is matched literally, so the + in c++ needs no escaping.
• A regular expression matches wherever it matches, including in the middle of a word. VLAN\d+ colours VLAN10 and VLAN200, but also the VLAN10 inside XVLAN10. Wrap the pattern in \b to limit it to whole words: \bdc[0-9]-[a-z]+\b matches hostnames like dc1-core and nothing longer.
• Your rules are tried first. Before the built-in highlighting, so where they overlap, your colour wins. For example, a Words rule for shutdown in the bad category overrides however the built-in set would colour it.
• Regular expressions ignore case too, and are checked when you click Add. One that does not compile is refused with the message "That regular expression does not compile", and nothing is saved.
• Everywhere at once. Rules apply to every terminal and persist between launches. Text that the far end already coloured is still left alone.
• The rule list. Each saved rule shows a swatch of its colour, the pattern, its type and category (for example words · bad), and a ✕ that removes it.

Categories

The colour names are the terminal palette slots. The exact shade comes from your terminal colour scheme, so the same rule looks right in Dracula, Nord, or Solarized.

How to use it

1. In Settings, make sure Colorize terminal output is ticked, then go to Custom highlight rules beneath it.
2. Type your pattern in the box, for example CRIT, DOWN, err-disabled.
3. Choose Words for a list, or Regex for a regular expression.
4. Choose the category whose colour matches should take, for example bad for failures.
5. Click Add, or press Enter in the pattern box. The rule appears in the list and takes effect on output from then on.
6. To remove a rule, click the ✕ at the end of its row.

Links in output

Hover a URL to underline it and see where it goes. Ctrl-click opens it in your browser. A plain click never opens anything, so finishing a text selection on a URL can't launch a browser by accident. A link that wraps across the edge of the pane is recognised as one link.

Find in output

Search everything in a terminal's scrollback, not just what's on screen.

How it works

A find bar opens over the focused terminal. As you type, every match in the scrollback is highlighted and the bar shows how many there are. If you had text selected, the bar starts with it. Aa makes the search match case. .* treats the search as a regular expression, so err(or)?|fail finds all three words at once.

How to use it

1. Click in a terminal and press Ctrl + Shift + F, or choose Terminal > Find in Output….
2. Type what you're looking for.
3. Press Enter to go to the next match and Shift + Enter for the previous one.
4. Press Escape to close the bar and go back to the prompt.

Scrollback

Terminals keep 10,000 lines by default. You can set anything from 1,000 to 100,000 in Settings. Every retained line is held in memory for each terminal, so a high setting across many tabs adds up. Raise it when you need to, not by default.

Clipboard and paste

Pasting into a terminal is where most accidents happen, so Xpecter handles it carefully.

• Right-click to paste is on by default. Copy on select (copy as soon as you select text) is off by default. Ctrl + Shift + V pastes everywhere.
• Line endings. Multi-line paste translates line endings to what a terminal reads as Enter, so text copied from Windows doesn't arrive with a blank line after every line.
• Bracketed paste. Many modern shells and editors support a mode where pasted text is marked as a paste. There, a pasted block lands on the prompt as one piece and waits for you to press Enter, instead of running line by line.
• Warn before pasting multiple lines (on by default). Network hardware and older programs don't support bracketed paste, so each line runs as it arrives. Before a paste like that, Xpecter asks first and shows a preview of exactly what's about to be sent. The prompt only appears when it matters: a paste of two or more lines into a program that has bracketed paste turned on goes straight in, because nothing runs until you press Enter. A multi-line command snippet always asks while this setting is on.

Delay between pasted lines

Some consoles, especially serial consoles at low baud rates and busy network devices, have small input buffers. A whole configuration pasted at once overflows them and characters are silently dropped. Delay between pasted lines adds a pause after every Enter, giving the device time to process each line before the next one arrives.

1. Set a delay in Settings > Clipboard & paste; it applies to every paste.
2. Or choose one in the paste prompt when it appears. Xpecter remembers what you pick for next time.

Command snippets

Snippets save a named command or configuration block that you use often. Create them in Terminal > Manage Command Snippets…. Each one appears in the Terminal menu as Snippet: name. Choosing it types the text into the focused session through the same paste guard, so a multi-line snippet gets the same preview and delay as a paste.

OSC 52

OSC 52 is an escape sequence that lets a remote program, such as tmux or vim over SSH, write to your local clipboard. It's useful, but any program on the host could use it to replace what's on your clipboard, so it's off by default. Turn it on under Settings > Security.

Zoom, fullscreen, and the cursor

Ctrl + = and Ctrl + - zoom the focused terminal's font, Ctrl + 0 resets it, and F11 toggles fullscreen. Cursor (Block, Underline, or Bar) and Blinking cursor in Settings > Terminal apply to every open terminal at once.

Saving output and clearing the screen

Save Terminal Output… (Ctrl + Shift + S) writes everything in the focused terminal's buffer, including scrollback, to a file you choose. It also works from the panel shown after a session drops. Terminal > Clear Screen clears the buffer.

The editor

The editor is a kind of session, not a fixed panel. That means it can go anywhere a session can.

• Open it as a whole tab with Sessions > New Text Editor, Tools > Text Editor, or picker choice 7.
• Or put it in one pane of a split, beside a shell.

Two editor panes can sit side by side, each with its own files. Ctrl + S always saves the document showing in the pane you're working in.

Documents

Each editor pane has a strip of open documents along the top. Click a document to switch to it, drag to reorder, or use Ctrl + PageUp and Ctrl + PageDown to step through. A modified document shows a dot in place of its close button, and the pane and tab carry the mark too, so unsaved work is visible from anywhere. Closing anything with unsaved changes asks: Save, Discard, or Cancel.

File commands

These are available from the command palette (Ctrl + Shift + P), and some have shortcuts:

• New File (Ctrl + N), Open File… (Ctrl + O), Save (Ctrl + S), Save As… (Ctrl + Shift + S), Close File (Ctrl + W)
• Save to Remote Host… writes the current buffer over SFTP to any host you're connected to. It's handy for pushing a config you drafted locally.
• Reload From Disk discards your changes and rereads the file.
• Run File, Delete File…, Copy File Path, and Open Outside Xpecter (opens the file in its default application)

The workspace tree

Open a folder to browse and manage its files inside the editor pane.

How to use it

1. Click the folder button on the document strip, then Open Folder….
2. The folder appears as a tree inside the pane, so a split can hold a folder and editor on one side and a shell on the other.
3. Click folders to expand them; each one opens and closes independently. Files that are open in the editor are marked in the tree.

The tree watches the folder, so a file added by anything else, such as a build, a download, or a shell in the next pane, appears on its own.

Create, rename, delete

The tree header adds a file or folder at the root, and every folder row does the same inside that folder. Every row can be renamed in place or deleted. If a name is already taken, Xpecter refuses rather than overwriting the existing file. Nothing goes to the recycle bin, so the delete confirmation names the full path and, for a folder, counts how many items will go with it.

Resize

Drag the tree's edge to make it wider or narrower, and double-click the edge to reset it. The width is remembered.

Find in files

Search every file in the open folder for text or a regular expression.

1. Click 🔍 on the tree header, press Ctrl + Shift + F with the caret in the editor, or choose Find in Files… in the palette.
2. Type your search. Choose whether to match case, and whether to treat the search as a regular expression.
3. Results take the tree's place, grouped by file, each with its line number and the matching line. Click a result to open the file at that line.
4. Press Escape to bring the tree back.

To keep results fast and relevant, the search skips version-control folders (such as .git), dependency folders (such as node_modules), build output, and binary files.

Show in File Explorer

This jumps from Xpecter to the same place in your system's file manager: Explorer on Windows, Finder on macOS, or your desktop's file manager on Linux.

• The ⧉ button on the tree header opens the open folder.
• Right-click any row: on a folder, it opens that folder; on a file, it opens the containing folder with the file selected.
• It's also on the folder menu, on document tabs, in the palette, and beside each pinned folder in the sidebar.

Pinned folders

From the folder menu, pin the folder to the sidebar's Folders section. After that, one click opens it in an editor again, even after a restart.

Opening anything, PDFs, and images

Every row in the tree opens something, whatever the file type.

How it works

• Text opens in the editor.
• PDFs and common images open in Xpecter's own viewers, as a tab in the document strip like any other document.
• Everything else goes to the application your system uses for that file type. That includes programs, archives, office documents, media, databases, and any file whose contents turn out to be binary.
• Programs always ask before they run.

Reading PDFs

The PDF viewer fits the page to the pane. It has zoom, actual-size, and fit-width buttons, and a page counter that follows as you scroll. A PDF on a remote host opens straight from the host in the remote browser, with no download step.

Viewing images

PNG, JPEG, GIF, WebP, BMP, ICO, SVG, and AVIF open in an image viewer with the same zoom controls. Transparent areas show against a checkerboard, so you can tell them apart from white.

Zooming

In both viewers, pinch on a trackpad, Ctrl-scroll, or press Ctrl with +, -, or 0. Zoom centres on the point under the cursor, so you zoom into what you're looking at.

Running a file

Run the file you're editing without leaving Xpecter.

How it works

Clicking Run saves the file first, then runs it. HTML opens in your browser. Scripts run in a live shell opened in the file's own directory, so relative paths work, the output stays on screen, and Up then Enter runs the script again. A script opened from a remote host runs on that host.

How to use it

Click the Run button on the document strip, or choose Run File in the palette.

Editing commands

• Find and replace: Find (Ctrl + F), Replace (Ctrl + H), Go to Line (Ctrl + G), and Go to Symbol
• Tidying: Format Document, Toggle Line Comment, Trim Trailing Whitespace, Sort Lines, and Transform Case
• Folding: Fold All and Unfold All
• File settings: Set Language…, Set Indentation…, Set Line Endings…, and word wrap (Alt + Z)
• Navigation: Ctrl + P jumps to any file in the workspace by name, Ctrl + Shift + P opens Xpecter's command palette, and F1 opens Monaco's own palette for everything else

Each pane's status bar shows the path, line and column, indentation, line endings, language, and wrap state. Click line endings, language, or wrap there to change them.

Languages

The editor ships Monaco's full language set, with language services (completion, errors, and formatting) for TypeScript, JavaScript, JSON, CSS, SCSS, Less, and HTML. It adds Haskell, PureScript, Idris, Elm, OCaml, Standard ML, Erlang, Nix, Lisp, Agda, and Lean.

Skald, Dawnrail's switch-configuration language, is a first-class language for .skald files. Plain text and log files (.txt, .log, .out, .err, .text) are coloured with the same highlighting the terminal uses, instead of showing as one grey wall.

Editor wallpaper and font

The editor uses the terminal's font and size, but has its own wallpaper image and opacity. A picture that reads well behind a prompt is usually noise behind code, so the two are set separately.

Remote files over SFTP

When an SSH session has focus, the sidebar's Remote files section shows that host's filesystem over SFTP. It uses the same connection, so there's nothing extra to log in to. The header names the session and has four buttons: + new file, ⊡ new folder, ⤒ upload files, and ⟳ reread.

• Navigate by clicking folders; 📁 .. goes up a level.
• Open a file by clicking it. It opens in an editor pane, and Ctrl + S writes it back to the host. PDFs and images open in Xpecter's viewers straight from the host.
• Shift-click or middle-click opens a file in your system's default application instead.
• Automatic refresh. The list rereads itself, so a file written by the terminal beside it appears without a manual refresh. Refreshing pauses while the section is closed or the window is in the background, to avoid loading the host for nothing.

Save as root

This lets you edit a file your login can read but not write, such as /etc/nginx/nginx.conf, and still save it from the editor.

How it works

When the host refuses a save because of permissions, Xpecter offers to save through sudo instead. It saves in two steps:

1. It writes your buffer to a private temporary file on the host that only your user can read.
2. It runs one sudo command that copies the temporary file over the original, keeping the original's owner and mode.

Your sudo password is sent once for that command and never kept. If sudo refuses, for example because of a wrong password or no sudo rights, the dialog shows sudo's own message.

How to use it

1. Open the file from Remote files, edit it, and press Ctrl + S.
2. When the save is refused, accept the offer to save as root.
3. Enter your sudo password. The file is replaced and the document is marked saved.

Edit externally

This lets you work on a remote file in a desktop application, such as a spreadsheet in Excel or an image in an image editor, and have your saves go back to the host.

How it works

The ✎↗ action downloads the file to a temporary copy and opens it in your system's default application for that file type. Xpecter watches the copy. Every time you save it in that application, the file is uploaded straight back to the host, and the status bar notes each upload. When the SSH session closes, the local copy is removed.

How to use it

1. In Remote files, click ✎↗ on the file.
2. Edit it in the application that opens, and save as usual.
3. Watch the status bar for the upload confirmation. Keep the session open until you're finished.

Upload and download

• Upload: drag files from your desktop onto the list, or click ⤒ and choose them. A progress bar appears under the list.
• Download: click ⤓ on a file, or on a folder to download it with everything inside, and choose where to put it.

How it works

Every transfer, in either direction, is written under a temporary name and renamed only when it finishes. If a transfer is cut short, you never end up with half a file under the real name, which matters when that file is a config a service is about to read. Modification times are preserved where the server supports it.

Create, rename, delete

These work on the host with the same confirmations as the local tree. SFTP has no trash, so deletion is permanent. The delete dialog says so, and counts what a directory holds before you confirm.

The remote browser follows the shell

With this on, the file list follows your shell. Type cd /var/log in the terminal and the list beside it moves to /var/log.

How it works

A remote shell doesn't normally tell the terminal which directory it's in. This feature relies on OSC 7, a standard, invisible escape sequence that the shell prints after each command with its current directory. Xpecter reads that sequence and moves the list. Many other terminals read OSC 7 too, so the line you add does no harm elsewhere.

How to use it

1. Make sure Remote files follow the shell's directory (needs shell integration) is ticked in Settings > Terminal. It's on by default.
2. Open View > Shell Integration…. It shows one line each for bash, zsh, and fish, with a Copy button beside each.
3. Add the line to the matching startup file on the host: ~/.bashrc, ~/.zshrc, or fish's config file.
4. Start a new session, or reload the file with source ~/.bashrc. From then on, every cd moves the list.

Tunnels and tools

Port forwarding

Port forwarding tunnels network connections through an SSH session. It lets you reach services that are only reachable from the far side, or let the far side reach something on your machine.

The three kinds

How to use it

1. Connect the SSH session you want to tunnel through.
2. Open Tools > Port forwarding….
3. Pick the session and the kind, then fill in the addresses as in the examples above.
4. Click Add forward. The forward appears in the active list.
5. To stop it, use its stop action. Forwards also stop when their session ends.

For a quick local forward, Terminal > New Local Port Forward… sets one up through a series of prompts instead of the dialog.

Forwards saved with a session

If you use the same tunnel every time you connect to a host, save it with the session and it starts on its own.

How it works

Saved forwards are part of a saved session. Every time that session connects, its forwards start automatically. If one can't start, for example because the local port is already in use, a message on the terminal says so and the connection carries on without it.

How to use it

• Start a forward as above, then click 📌 beside it in the active list. It's added to the saved session it runs through.
• Or right-click the session, choose Edit session, and add, change, or remove forwards in the Port forwards list under Advanced settings.

Network tools

Tools > Network tools… holds two utilities that run from this machine and need no session.

Appearance

The Appearance group at the top of Settings applies to every window, tab, and pane at once. Changes take effect immediately and persist.

How it works

• Theme colours the window itself: title bar, menus, sidebar, dialogs. Terminal colors is separate and colours only what's inside terminals, so a light window with a dark terminal is fine. Output highlighting takes its colours from the terminal scheme.
• Font and Font size apply to terminals and editors alike. If the chosen face isn't available, Xpecter falls back to Consolas, then to your system monospace font. Eight faces ship with Xpecter and look the same everywhere: Cascadia Code, Fira Code, IBM Plex Mono, Inconsolata, JetBrains Mono, Source Code Pro, Ubuntu Mono, and Victor Mono. Menlo, Consolas, and Courier New come from your system. Menlo is a macOS font, so on Windows and Linux the default shows as Consolas or your system monospace font.
• Wallpaper. After you pick an image, two more rows appear under it: an Opacity slider from 0 to 60 percent (15 to start) and Clear wallpaper to remove it. Low opacity keeps text readable. Terminal wallpaper uses the canvas renderer instead of WebGL.
• Editor wallpaper works the same way, with its own Editor opacity and Clear editor wallpaper. It's separate because a picture that reads well behind a prompt is usually noise behind code.

How to use it

1. Open Settings. Appearance is the first group.
2. Pick a theme, colour scheme, font, and size from the dropdowns.
3. For a wallpaper, click Browse… beside Wallpaper or Editor wallpaper and choose an image, then drag its opacity slider until text reads comfortably.

Settings reference

Open Settings from the title bar's Settings menu. It's one scrolling dialog in the order below, and every change takes effect immediately and persists; there is no Save button. Close it with ✕, Esc, or a click outside it. This is every setting in Xpecter 3.8, with its exact label.

Appearance

Theme, Terminal colors, Font, Font size, Wallpaper (with Opacity and Clear wallpaper), and Editor wallpaper (with Editor opacity and Clear editor wallpaper). See Appearance for the choices and defaults of each.

Terminal

Clipboard & paste

Security

This group has a coloured edge down its left side, because both settings loosen a default that protects you.

Session logging

Configuration

These are actions rather than settings; click one to run it. Each is explained in full under Your configuration or Importing sessions.

About

Shows the version you're running beside Check for updates…, which asks GitHub for the latest release. More

Keyboard shortcuts

View > Keyboard Shortcuts… lists every binding. To change one, click it and press the new keys. Custom bindings persist. Reset appearance settings to defaults puts them back, along with other settings; see Resetting for everything it touches.

In an editor pane

Ctrl + Shift + S and Ctrl + Shift + F do different things depending on focus: in a terminal they save output and find in output, and in an editor they mean Save As and find in files. Every dialog closes with Esc or a click outside it.

Your configuration

Where it lives

Xpecter keeps its configuration as plain JSON in your OS config directory. Sessions, folders, local shell profiles, layouts, and settings each have their own file, and only your user account can read them.

Backups

Xpecter writes a backup of your configuration at most once a day and keeps the seven most recent. To roll back, for example after deleting sessions by mistake, choose Settings > Restore from backup… and pick a date.

Export and import

Export configuration… writes your sessions, groups, profiles, pinned folders, layouts, and appearance settings to a single file. It's how you move your setup to a new machine or share a session list with a colleague. Passwords are never written to a configuration file.

Import configuration… reads that file and asks how to apply it:

• Replace makes this machine match the file exactly. Anything not in the file is removed.
• Merge adds the file's contents alongside what you already have.

Encrypted bundles

Export encrypted configuration… and Import encrypted configuration… work the same way, but protect the file with a passphrase you choose. The passphrase is stretched into a key with PBKDF2-SHA256 and the bundle is encrypted with AES-256-GCM, which also detects tampering. The bundle is safe to keep in OneDrive, Dropbox, S3, or any file store, with no Xpecter service involved. Encrypted bundles still never include passwords or host keys. If you forget the passphrase, the bundle can't be opened.

Resetting

• Reset appearance settings to defaults asks "Reset all settings to defaults? Saved sessions will not be changed." and goes further than its name suggests. It resets:
  • Theme, terminal colours, font, font size, and both wallpapers
  • Keyboard shortcuts
  • Scrollback, SSH keepalive, Keep app open when last tab closes, Show tab numbers, and Colorize terminal output
  • Copy on select, Right-click to paste, and Warn before pasting multiple lines
  • OSC 52, back to off
  • Session logging, back to off, forgetting the log directory
  • Remember SSH passwords, back to off. Passwords already in the keychain are not deleted by this; untick the setting yourself, or use Forget saved password, to remove them.
  • Command snippets, which are deleted. Export your configuration first if you want to keep them.
  It leaves sessions, folders, layouts, custom highlight rules, tag colours, the cursor settings, bell notifications, following the shell's directory, the paste delay, and On launch as they are.
• Erase all saved data… clears everything. It writes a backup first and refuses to go ahead if that backup fails, so an erase can always be undone with Restore from backup.

Security

• Host keys. Every SSH connection, including to a jump host, is checked against your own ~/.ssh/known_hosts. An unknown host shows its fingerprint and asks. A changed key shows a stronger warning, because it can mean the machine was rebuilt or that someone is intercepting the connection.
• Passwords. By default, Xpecter stores no passwords anywhere. The only exception is the opt-in OS keychain, and that is never Xpecter's own file.
• Keys and agents. Private keys and passphrases are never saved in session profiles. The memory agent holds an unlocked key for one app run only. Forward your agent only to hosts you trust.
• Protected sessions. A tag set to ask before pasting, such as prod, makes every paste that presses Enter, and every snippet, ask first.
• Clipboard. OSC 52 clipboard writes from remote programs are off by default.
• Programs. Opening an executable from a file tree always asks first.
• Sudo saves stage the file with owner-only permissions and send the password once, never keeping it.
• Encrypted bundles never include passwords or host keys.

Limitations and things to know

• macOS builds are not notarized yet, so the first launch needs right-click > Open.
• Remote Desktop and VNC are drawn by your platform's own client, not inside the Xpecter window. A webview isn't the place for a native desktop protocol.
• ZMODEM transfers over the terminal (sz and rz) aren't supported; use the SFTP browser and its transfer actions to move files.
• Font ligatures aren't rendered.
• Serial sessions take a typed port name; there's no list of detected ports yet.
• Telnet and Mosh run your system's clients, which must be installed. X11 forwarding needs a local X server.
• Tabs can't be dragged between windows.
• Files can't be dragged out of the remote browser onto the desktop; use the ⤓ action to download.
• Cloud-provider browsing, background sync, macro recording, and plugins aren't part of the product today.

Reporting problems

Xpecter is developed in the open on GitHub. If something breaks, or works differently from what you expected, open an issue on GitHub. Include:

• Your platform
• The version from Settings > About
• The kind of session you were in
• What happened, and what you expected to happen

A useful report can be as simple as "this crashed" or "I wish X worked like Y."

Attaching the log

View > Open Log Folder opens the folder that holds xpecter.log. It records connections, transfers, and any error the window caught, and it's rotated so it never grows without limit. Attach it when something went wrong and you couldn't tell why.