Berth User Manual

SFTP, terminal, and serial console in one window — from adding a server to keyboard shortcuts

🚀Getting Started

Screen Layout

One window holds four areas.

• Site Sidebar — on the left. Servers, serial consoles, and folders appear as a tree.
• Session Rail — the sessions you're connected to. A color stripe shows which server each one is.
• Workspace — the file panels (local and remote) on top, the terminal below. Drag the divider to change the ratio.
• Status Bar — at the very bottom. Shows what's happening right now.

Adding Your First Server

1. Right-click an empty area of the sidebar, or press ⌘N.
2. Enter a name and the server address. Leave the user and port blank to use the defaults.
3. Double-click an item in the list to connect. A single click just selects it.

Changing the Language

Choose one of 20 languages from the Berth › Settings menu (⌘,). Following the system language is the default, and the language you choose applies only to this app. The change takes effect after you restart the app.

🗂Servers and Folders

Grouping into Folders and Inheriting Settings

Group servers into a folder (⌘⇧N) and settings flow down to them. Set a username or caution tier once on the folder, and every server underneath follows it. This exists so you don't have to enter the same value twenty times for twenty servers.

Each field in the settings window notes where its value came from (whether you set it, or which folder it was inherited from) below the field, and a reset button returns it to the inherited value.

Caution Tier — Development · Staging · Production

Tier outranks color. Set to Production and risky actions ask for extra confirmation. In the session list it's filled with your chosen color and marked with a red border, so several production servers are still told apart by color. Where only one shows at a time — confirmation dialogs and the like — it stays red as a strong warning.

Click Rules

• Single click — select (for viewing settings or moving it)
• Double click — connect for a server, expand/collapse for a folder
• The triangle in front of a folder expands it with a single click.

🔑Connecting and Authentication

First Connection — Folder Permission

Berth follows App Store rules (sandboxing), so it doesn't read your home folder freely. The first time you open a server, it asks you to choose, once, the folder holding your SSH config, keys, and known_hosts (usually ~/.ssh). Once you choose it, Berth remembers and won't ask again. If you keep your keys elsewhere, you can choose your home folder instead.

For the same reason, the local file panel also uses the folder you chose as its root — you can change it with Open Local Folder… in the panel header, and that choice is remembered too.

Reading ~/.ssh/config

Connecting by alias reads and uses that entry's host, port, user, key file, ProxyJump, and StrictHostKeyChecking. Even if the saved port is out of date, the config file wins.

Authentication Method

• Automatic — leaves it to ssh. It tries all default keys, and if that fails, asks for the password in the terminal.
• Key File — uses only the one key you specify.
• Password — skips keys entirely.

When the Server Asks

If you save a password, Berth answers once for you when connecting. Any other prompt — a two-factor code, retyping a wrong password, or the password for a key that has one — is shown exactly as the server sent it in the "The server sent a request" window, for you to answer yourself. To keep your account from being locked, a saved password is entered automatically only once, and you're asked at most three times.

To Stop Typing the Password

Right-click a server and choose Register Public Key on This Server… to upload the public key in ~/.ssh to it. After that, you'll connect with the key.

A saved password lives only in macOS Keychain. The config file keeps only a note that it's "saved" — never the value itself.

A New Server, or a Changed Host Key

For a server you're connecting to for the first time, Berth shows the key type and fingerprint and asks whether to remember it. If you do, it's written to ~/.ssh/known_hosts in the same form ssh uses, and you won't be asked again.

This also appears when the server's identity is different from last time. It could be a man-in-the-middle attack, or the server may have been reinstalled. Berth doesn't judge for you — it gives you the material: the old and new key types and fingerprints, and even the command to compare directly on the device console. After you've checked, clicking "Remove Old Key, Remember New Key" removes the old entry (backed up to known_hosts.old) and writes the new key.

File Panel (SFTP)

Uploading and Downloading

The left side is your Mac, the right side is the server. Drag and drop, or send with ⌥⌘→ (upload) and ⌥⌘← (download). Progress stacks up in the transfer row.

The File Panel That Follows the Terminal

cd in the terminal, and the remote panel follows into the same folder. When that following gets in the way, turn it off with ⌘⇧L.

Places You Visit Often · Views

• ⌘D — pins or unpins the current path to the Pin. A pin becomes a root in the tree.
• ⌘↓ — drills into the selected folder. ⌘↑ goes back up one level.
• ⌥⌘T — Tree ↔ List view. For a folder with thousands of files, List is better.
• ⌘R — Reload.
• ⌘⇧F — Find on Server. The server runs find, not the app scanning the list itself.

Viewing Differences (Diff)

Turn it on with ⌘⇧Y to compare local and remote side by side and mark what differs, or exists on only one side. Use it when you only want to send what's needed.

Deleting

⌘⌫ defaults to moving items to the server-side Trash, and always asks for confirmation. On a server where Trash is off, it tells you up front that this can't be undone.

⌨️Terminal

It's a real shell where vim, tmux, and less run just as they do anywhere else. Select by dragging with the mouse and copy with ⌘C — a copied command pastes cleanly, without the padding spaces at the end of the line.

Paste Confirmation

Paste multiple lines, and Berth shows you what will run first. That's because a paste containing line breaks becomes commands on the spot. Anything that looks risky is flagged along with the reason.

Zooming In

⌘↩ zooms the current area in, and pressing it again returns. ⌥⌘↩ enlarges only one panel. Font size is ⌘+ · ⌘- · ⌘0. Clear the terminal with ⌘L — the screen and scrollback are wiped, leaving just the current prompt line.

🔌Serial Console (UART)

Choosing a Device

Add a serial console with ⌃⌘N, then choose the connected device in Settings. Berth remembers the device, not the path — by serial number if it has one, otherwise by kind. It finds the same device even when plugged into a different USB port.

Speed and Line Settings

Choose the speed from the list, or type one in directly (non-standard rates like 1,500,000 also work — it just needs to be a rate the adapter accepts). The default is 8N1 · no flow control, which most consoles use.

• Flow Control — turn it on only with a 4-wire cable (RTS/CTS). Turning it on with a 3-wire cable actually blocks communication.
• Advanced (parity · bits) — click the row to expand it. Use it only when different, like an STM32 bootloader (8E1).

History

In a serial session, the commands you type and their responses stack up on the right along with the time. Input at a password prompt is masked.

⚡Shortcuts

An app shortcut always includes ⌘. ⌃/⌥ combinations belong to the shell and TUIs (vim, tmux), so the app never claims them.

❓FAQ

Where Are Passwords Stored?

It's stored only in macOS Keychain. The config file keeps only a note that it's "saved." Keychain is opened just once, at the moment you connect.

Does It Collect Usage Data?

No. There's no instrumentation of any kind inside the app. It doesn't count what you open or what you connect to.

The Serial Console Stops Partway Through.

This is a property of the line itself, showing up when there's heavy traffic on UART with no flow control. If you have a 4-wire cable, turn on flow control (RTS/CTS) in Settings; with a 3-wire cable, try lowering the board's baud rate or splitting the output through a pager.

Do I Need to Re-enter My Existing SSH Config?

No. Importing from ~/.ssh/config connects using the alias as-is, reading and using that entry's host, port, user, key, and ProxyJump.

I Have a Config That Uses ProxyCommand.

ProxyCommand launches an external program, so it can't be used in the App Store sandbox. If your config goes through a jump host, switching to ProxyJump works just the same. ssh-agent can't be used for the same reason — Berth reads key files directly, and for a key with a password, it asks for the password when connecting.

Which macOS Versions Are Supported?

macOS 14 (Sonoma) or later, on both Apple Silicon and Intel.

If This Helped

Berth is free. You can support its development by donating.