K-Shell documentation

Getting started

K-Shell is a desktop app for SSH terminals, SFTP and FTP, object storage (S3-compatible, Azure Blob, Google Cloud Storage) and SSH port forwarding. It runs on macOS, Windows and Linux. There is no account and no cloud service: everything is stored on your computer.

Install

Download the installer for your system from the download section or keselyoleren.com/download, which picks the right file for your OS. macOS gets a .dmg, Windows an .msi or .exe, Linux a .deb, .rpm or .AppImage.

Your first connection

1. Open Hosts in the sidebar and click New Host.
2. Pick SSH / SFTP, enter the Address, Username and a Password or SSH key, and click Save. Test checks the connection without saving.
3. Double-click the host card (or click its connect button) to open a terminal tab.

Already using OpenSSH? Click Import on the Hosts page to bring in ~/.ssh/config, or just press ⌘K, type user@host and press Return to connect without saving.

Hosts

A host is a saved connection. Each one has a protocol at the top of the editor:

Fields

• Address and Port, a Label (shown instead of the address) and a Group.
• Credentials: Username (empty means root for SSH), Password and, for SSH, an SSH key from the Keychain.
• Advanced (SSH): Jump host (ProxyJump), Startup command (typed into the shell after connecting, e.g. cd /var/www && tmux attach || tmux) and Agent forwarding.
• Appearance: a colour, Tags (comma separated) and Notes.

Object storage hosts have their own fields; see Object storage.

The Hosts page

• Hosts are grouped by Group. The chips at the top filter by group; Search hosts… matches label, address, username, group and tags.
• Recent shows the hosts you used last. Switch between Grid and List view.
• Double-click a host to connect. Right-click for Connect, Open SFTP, Test connection, Port forwarding…, Edit, Duplicate, Copy address and Delete.
• After the first SSH connection, K-Shell detects the server's OS (Ubuntu, Debian, Alpine, …) and shows it as the host's badge, unless you picked a colour.

Jump hosts

To reach a server behind a bastion, choose the bastion in Jump host (ProxyJump). The bastion can have its own jump host, so chains like laptop → bastion → … → target work. ProxyJump entries are imported from ~/.ssh/config.

Import from ~/.ssh/config

Import on the Hosts page (also in Settings → Vault & backup) reads hosts, users, ports, identity files and ProxyJump from your OpenSSH config.

Authentication & keys

When connecting over SSH, K-Shell tries these methods in order and uses the first one that works:

1. The SSH key selected for the host, from the Keychain.
2. The Password, first as password authentication, then as the answer to keyboard-interactive prompts.
3. Your ssh-agent (SSH_AUTH_SOCK; on Windows the OpenSSH agent or Pageant).
4. The default keys ~/.ssh/id_ed25519, id_ecdsa and id_rsa, if they have no passphrase.

Keychain

• Generate Key creates an Ed25519, ECDSA or RSA (4096-bit) key, with an optional passphrase.
• Import takes an existing private key (OpenSSH or PEM), pasted or loaded with Choose file….
• Copy public key copies it to the clipboard.
• Install on host… appends the public key to ~/.ssh/authorized_keys on a saved host, like ssh-copy-id.
• The Grid and List buttons switch how keys are shown.

Keys and passwords are stored in the encrypted vault, never in plain text. See Security & your data.

Terminals & tabs

• Every SSH session and local shell opens in a tab. ⌘T opens a local terminal (also Local Terminal in the sidebar), ⌘W closes a tab.
• Rename a tab: double-click it, choose Rename tab in its right-click menu, or use Rename tab in the command palette. Leave the name empty to go back to the automatic title.
• Your tabs come back: when you open K-Shell again, the tabs of your last session reopen with their split layout and connect (Reopen tabs on launch in Settings). Hosts are remembered by reference, so no password or key is copied, and a host you deleted since is skipped.
• Drag a tab along the tab bar to reorder it. ⌃⇥ / ⌃⇧⇥ switch to the next or previous tab, ⌘1 goes to the Vault and ⌘2–⌘9 to an open tab.
• Find: ⌘F opens a search box. Return finds the next match, ⇧Return the previous one, Esc closes it.
• Copy and paste: selecting text copies it (Copy on select). A right-click pastes (Right-click pastes); ⇧+right-click opens the menu with Copy, Paste, Clear, Find…, split options, Open SFTP here (Open in file manager in a local terminal) and up to ten of your snippets. Both behaviours can be turned off in Settings.
• Pasting several lines: K-Shell shows them first and asks before pasting, because each line can run as a command (Warn before pasting several lines).
• Drop files: drop files or folders from Finder or Explorer onto a terminal to type their paths, quoted for the shell. With several panes, the one under the pointer gets them.
• Links: ⌘-click a URL to open it in your browser.
• Reconnect: when an SSH connection drops, K-Shell tries again after 1, 2, 4, 8 and 15 seconds, then every 30 seconds for about 3 minutes, and right away when the network comes back. Return reconnects now and ⌃C stops. After a session ends normally (you typed exit), press Return to connect again. Turn it off with Reconnect SSH automatically.

Working directory

K-Shell follows the folder your shell is in. A new split opens in the same folder, a reconnect or a reopened tab goes back to it, and Open SFTP here / Open in file manager open it. For bash and zsh, K-Shell adds a small hook when a session starts; shells that already report their folder work as they are. Turn it off with Follow the working directory in Settings → Terminal. In zsh, the hook's setup line can appear in your history unless HIST_IGNORE_SPACE is set.

Keyword highlighting

Words in terminal output are coloured by rules: by default errors in red, warnings in yellow and successes in green. In Settings → Terminal → Highlight keywords, each rule is a list of words (separated by commas) or a regular expression (.*), with a theme colour and an option to match case (Aa). Add rule adds one and Reset to defaults brings the defaults back. The output itself is not changed, and full-screen programs like vim or htop are left alone.

Session logs

Turn on Log terminal sessions in Settings → Terminal → Session logs to save what every new terminal prints to a plain-text file, one file per session, named after the date and the host. Colour and cursor codes are removed, and a progress bar is saved as its final state. Files go to Documents/K-Shell Logs unless you choose another Log folder; Open shows the folder.

Split panes

⌘D splits the focused pane to the right, ⇧⌘D splits it down. Drag the line between panes to resize. ⌘] and ⌘[ move focus to the next or previous pane.

Rearranging

• Move a pane: drag it by its header (the bar with its title). The other panes make room while you drag, and an empty slot shows where it will land. Esc cancels.
• Give a pane its own tab: drop it on the tab bar, or click Move to new tab in its header or right-click menu.
• Merge a tab into another: open the tab you want to split, then drag another terminal tab from the tab bar onto it. Rest on a tab for half a second while dragging to switch to it first.

Broadcast input

Press ⌥⌘I (Ctrl Shift I), or choose Broadcast input to all panes in a pane's right-click menu or the command palette, and what you type, paste or run as a snippet in one pane goes to every pane of the tab. Broadcasting panes get an amber border and the tab shows a broadcast icon. Click the icon in a pane's header (or Leave this pane out of broadcast) to leave that pane out. Broadcast turns off by itself when the tab is down to one pane.

Moving panes never disconnects them: SSH sessions and running programs keep going. With Confirm before closing split tabs on, K-Shell asks before you close a tab that has several panes from the tab bar (its × button or a middle-click).

Workspaces

A workspace groups the local project folders you work on together, for example one workspace per client or product. Open Workspaces in the sidebar.

1. Click New workspace, give it a name and a colour.
2. Click the + button (Add project) or the Add project tile at the end of the workspace, and choose a folder. The name is taken from the folder; you can change it.
3. Optionally add a Startup command, e.g. git pull && npm run dev, typed into the terminal when the project opens.

• Click a project to open a local terminal in its folder. The tab is named after the project and uses the workspace colour.
• Open all opens every project of the workspace in its own tab.
• Projects show as cards or as a compact list: switch with the Grid and List buttons. Paths in your home folder are shown as ~/…, and a project can be opened with Return from the keyboard.
• Projects that are open show a badge such as 1 open, and the workspace shows how many terminals are open in all. Right-click a project to edit, reorder or remove it. Removing a project or workspace never touches the folder itself.
• Projects can be found in the command palette; typing a workspace name offers Open workspace ….

If a folder was moved or deleted, the terminal shows Folder not found. Edit the project to point it at the new location.

Autosuggestions

As you type in a terminal, K-Shell shows the rest of a command you ran before in grey.

• → accepts the whole suggestion, ⌥→ (Ctrl → on Windows/Linux) accepts one word. When no suggestion is shown, the keys work as usual.
• Commands run on the same host or in the same workspace project come first, then other history, then your snippets.
• Suggestions pause after you use ↑, Tab or the shell's history search, because the line then comes from the shell; they come back after the next Return. They're not shown in full-screen programs like vim or htop, or when your shell already draws its own suggestion.

Privacy

History is kept in the encrypted vault (the last 2,000 commands). Anything that isn't shown on screen as you type, such as passwords, is never saved, and neither is a command that starts with a space. Manage it in Settings → Terminal → Autosuggestions: turn suggestions off, turn off Remember command history (then history lasts until K-Shell quits), or Clear it.

K-Shell prompt

Build your own shell prompt without editing dotfiles. Go to Settings → Terminal → Prompt, turn on K-Shell prompt and click the preview to edit it.

• Click a segment or drag it into the prompt; drag to reorder, drag it back out (or press ⌫) to remove it. Restore default resets it.
• Segments: user@host, user, host, directory, directory name, git branch, Python venv, conda env, kube context, time (24h or 12h), date, exit code, prompt symbol and line break. Segments that don't apply right now (no git repo, last command succeeded…) are hidden automatically.
• Long directories are shortened from the left to 40 characters, e.g. …yoleren/project/chronicle/fork/core-api.
• Apply to chooses All sessions, Local or SSH.
• Copy for .bashrc / .zshrc gives you the same prompt to paste into your shell config, so it also works outside K-Shell.

File Manager

The File Manager has two panes. Each pane can be your computer (Local) or any saved SFTP, FTP, FTPS, S3, Azure Blob or Google Cloud Storage host, so you can copy between any two of them. Open it from File Manager in the sidebar, Open SFTP on a host, or Open SFTP here in a terminal.

• Transfer: drag files and folders from one pane to the other, or right-click and choose Upload to … / Download to …. Folders are copied recursively. You can also drop files from Finder or Explorer onto a remote pane.
• Queue: up to three transfers run at once. The Transfers panel shows progress and speed; each transfer can be cancelled, and Clear finished tidies the list.
• Files: right-click for Rename, Permissions… (chmod), Copy path, Delete, New folder, New file, Refresh and Show hidden files.
• Select: click a file; ⌘-click adds or removes one, ⇧-click selects a range.
• Navigate: double-click a folder to open it, ⌫ goes up a level, double-click the path to type one. Delete (or ⌘⌫) deletes the selection.
• Open: double-click a file. Images open in a preview, PDFs, documents, media and archives in the app your computer uses for them, and everything else in the editor. Right-click for Open in default app or, for a file that isn't text, Edit as text.
• Edit: the editor highlights syntax for about 140 languages and config formats, picked from the file name, in the colours of your terminal theme. It has line numbers, find and replace (⌘F) and folding, and keeps the file's indentation and line endings. Text files up to 8 MB; ⌘S saves it back to the server, Esc closes.
• Edit in your own app: a remote file opened in another app is a downloaded copy that K-Shell watches. Save it there and the file manager shows it as changed with an Upload button. The × stops watching it.

Files that would run or install when opened (.exe, .msi, .pkg, .dmg, .jar, .sh and similar) are never opened from the file manager. Scripts can still be opened in the editor; download anything else you need.

Object storage

S3-compatible

Pick a Provider preset to fill in the endpoint and region: AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Wasabi, Backblaze B2, Google Cloud (HMAC keys), Tencent COS, Scaleway, Hetzner, Linode / Akamai and Oracle Cloud. Replace values in <angle brackets> with your account's. Then enter the Access key ID and Secret access key.

• Endpoint: empty means AWS.
• Bucket is optional; leave it empty to browse all buckets.
• URL style: Path-style (endpoint/bucket) for MinIO, R2 and most self-hosted services, Virtual-hosted (bucket.endpoint) for AWS and Tencent COS.

Azure Blob

Enter the Storage account name, an Account key or SAS token and the Container. Endpoint is optional. With a SAS token you can browse and transfer, but share links need the account key.

Google Cloud Storage

Enter the Bucket and paste a Service account key (JSON) or load it with Choose file…. Leave the key empty for public buckets (read-only).

Share links

Right-click a file and choose Copy share link to copy a link that works for 7 days: a pre-signed URL on S3, a read-only SAS link on Azure (needs the account key), a signed URL on Google Cloud (needs a service account key).

Port forwarding

Tunnels run through one of your saved SSH hosts. Open Port Forwarding in the sidebar and click New Rule, or right-click a host and choose Port forwarding….

Paste an ssh command

Already have the command? Paste it into Paste an ssh command, for example ssh -N -L 5431:localhost:5432 deploy@10.0.0.5 -p 2222. K-Shell fills in the rule and picks the saved host with the same address, port and user. Several -L/-R/-D flags create one rule each. If the server isn't saved yet, click Add host; Save stays disabled until then, so a tunnel never goes through the wrong server.

• Turn a rule on and off with its switch; ● active shows it's running, and the sidebar shows how many are active.
• Start automatically when K-Shell opens starts the rule on launch.
• Each rule shows its equivalent ssh command; the copy button copies it.
• Leave Name empty to get one like localhost:5432 → :5431 or SOCKS 1080.

Snippets

Save commands you use often under Snippets → New Snippet (name, command, tags).

• Variables: write {{name}} or {{name:default}} in a command, for example git checkout {{branch:main}}. K-Shell asks for the values each time the snippet runs and remembers the last ones until it quits. Values are inserted as typed, so add quotes in the snippet if you need them.
• Paste to terminal sends the command to your most recent terminal tab and runs it.
• Run on hosts runs it on several saved hosts at once and shows each host's output and exit code.
• Snippets also appear in the terminal's right-click menu and in the command palette, and are used for autosuggestions.

Command palette

⌘K (or ⌘P) opens the palette. Use ↑ ↓ and Return.

• Hosts by label, address, user, group or tag.
• Quick connect: type user@host or user@host:port to connect over SSH without saving the host.
• Workspace projects, and Open workspace … when you type a workspace name.
• Snippets by name or command.
• App commands such as Split right, Zoom in or Open settings, each with its shortcut.

Keyboard shortcuts

The defaults are below. Change any of them in Settings → Keyboard shortcuts.

Some actions have no default key but can be given one: Snippets, Keychain, Port forwarding, Workspaces, Open file manager, Rename tab, Close pane and Clear terminal.

Changing a shortcut

1. Open Settings → Keyboard shortcuts. Search by name or by keys (e.g. split or cmd d), or filter Customized, Conflicts or No shortcut.
2. Click the shortcut and press the new keys. Esc cancels, ⌫ removes it.
3. If the keys are already used, K-Shell asks whether to Replace. Keys a terminal program would normally receive (like ⌃L) get a warning; keys used by the macOS menu bar (like ⌘Q) can't be used.

The reset button on a row restores its default; Reset all restores every default. Custom shortcuts are saved separately for macOS and for Windows/Linux, so a backup restored on another system keeps sensible keys.

Settings

Open Settings at the bottom of the sidebar or press ⌘,. Changes are saved immediately.

Appearance

• Theme: Dark, Light or System (follows your OS).
• Accent color: a preset or your own colour for buttons, switches and highlights.
• Show sidebar: hide the menu on the left for more room, and bring it back the same way. Also with ⌘B, the sidebar button next to the K-Shell logo, or the button at the start of the tab bar while the sidebar is hidden. K-Shell remembers your choice.
• Zoom: scales the whole window, terminals included (⌘= ⌘- ⌘0).
• Terminal theme: 25 themes in Dark and Light groups, with a live preview. Turn on Match app light / dark mode to use a different theme while the app is light.

Terminal

• Font, Font size, Line height, Letter spacing, Font weight and Bold text weight, with a live preview. Bright colors for bold text and Minimum contrast help with hard-to-read colours.
• Prompt and Autosuggestions.
• Cursor: block, bar or underline, Blinking cursor, and the Cursor in unfocused panes.
• Keyboard & bell: on macOS, turn off Use Option as Meta key to type characters like @, € or [ with Option on non-US keyboards. Bell flashes the pane, beeps, does both or nothing.
• Scrollback lines, Copy on select, Right-click pastes, Follow the working directory, Warn before pasting several lines, Reconnect SSH automatically, Reopen tabs on launch and Confirm before closing split tabs.
• Highlight keywords and Session logs.
• Local terminal: the Shell new local terminals run (empty uses the system default) and the folder they Start in. Workspace projects keep their own folder.

Keyboard shortcuts

See Keyboard shortcuts.

Vault & backup

• Import ~/.ssh/config.
• Encrypted backup: Export… saves hosts, keys, snippets and rules to a passphrase-protected file; Restore… merges a backup into this computer. Use it to move your setup to another machine.

About

Shows your version and Check for updates. See Updates.

Security & your data

• No account, no cloud. K-Shell has no sign-in, no sync server, and no analytics or crash reports.
• Encrypted vault. Hosts, passwords, keys, snippets, rules, workspaces and command history are stored in one file encrypted with XChaCha20-Poly1305. The 256-bit key is kept in your system keychain (macOS Keychain, Windows Credential Manager, Secret Service on Linux). If no keychain is available, it is stored in a vault.key file next to the vault that only your user can read.
• Host keys. The first time you connect, K-Shell remembers the server's key (listed under Known Hosts). If the key changes later, the connection is stopped with a HOST KEY CHANGED warning. If you know the change is expected (e.g. a reinstalled server), delete the old entry in Known Hosts and connect again. K-Shell also respects a key change recorded in your ~/.ssh/known_hosts.
• Backups. Exported backups are encrypted with your passphrase (Argon2id + XChaCha20).
• Network. K-Shell connects only to the servers and storage you use, plus a check for new versions (see Updates).

Where the vault lives

Known limitations

• A server's key is trusted on the first connection without asking you to confirm its fingerprint.
• While K-Shell is running, secrets are decrypted in memory so the host editor can show them.
• There is no master password to lock the app yet.

Reporting a security problem

Please don't report security problems in a public issue. Send them privately through private vulnerability reporting, with the K-Shell version and OS, the steps to reproduce, and the impact you expect. Reports are acknowledged within 72 hours, and confirmed problems are fixed as fast as their severity requires. Only the latest release receives security fixes, so keep K-Shell up to date.

Updates

K-Shell checks for a new version shortly after launch and then every 6 hours. When one is out, an Update K-Shell button appears in the tab bar: one click downloads it, installs it and restarts the app. Updates are signed, and K-Shell only installs an update with a valid signature. You can also check by hand in Settings → About → Check for updates.

Troubleshooting

What's new

Get the latest version from the download section. If K-Shell is already installed, it offers the update itself (see Updates).

0.4.0 · 5 November 2026

• SSH sessions reconnect by themselves after a dropped connection, and your tabs reopen when you start K-Shell.
• Terminals follow the working directory: splits, reconnects and Open SFTP here use the shell's current folder.
• Broadcast input to every pane of a tab with ⌥⌘I.
• Keyword highlighting, session logs, a warning before pasting several lines, and dropping files on a terminal to type their paths.
• Rename tabs.
• The File Manager opens images in a preview and other files in their own app, offers to upload a remote file you saved in another app, and its editor highlights syntax.
• Snippet variables such as {{branch}}.
• 16 more terminal themes, a redesigned Workspaces page, grid or list in the Keychain, and more terminal settings.
• Faster start-up, and less memory used by terminals in background tabs.
• Fixed: agent forwarding, where ssh-add -l, git or ssh on the server hung or found no keys.

0.3.0 · 4 November 2026

• Show or hide the sidebar with ⌘B (Ctrl Shift B on Windows/Linux), a button, or Settings → Appearance → Show sidebar.

0.2.0 · 4 November 2026

• Workspaces for local project folders.
• Autosuggestions from your command history.
• The K-Shell prompt builder for bash and zsh.
• Drag panes and tabs to rearrange splits without disconnecting.
• Custom keyboard shortcuts, and new ones for tabs, panes, zoom and settings.
• Appearance: System theme, accent colour, zoom, a separate terminal theme for light mode.
• Port forwarding from a pasted ssh -L command, with the host matched for you.
• The command palette lists app commands with their shortcuts.

0.1.0 · 3 November 2026

First release of the desktop app: hosts, SSH terminals with tabs and splits, the File Manager for SFTP/FTP/FTPS and object storage, port forwarding, snippets, the keychain, the encrypted vault and in-app updates.