airscp

# AirSCP Help (all pages)

> AirSCP is a free, open-source Mac app (macOS 13.1 or later) for SSH servers and Windows desktops: saved hosts, a two-pane SCP/SFTP file browser with a background transfer queue, Synchronize, Find Files, remote file operations, a Linux monitor, tunnels, jump hosts and HTTP proxies, and a built-in Remote Desktop client with clipboard and file transfer. AI agents drive it over MCP once the user allows it.

- Install: `brew install --cask kleash/tap/airscp` (or the zip from https://github.com/kleash/airscp/releases).
- Agent control: the user turns on AirSCP ▸ Settings ▸ Allow AI agents to control AirSCP (MCP); then `claude mcp add airscp -- /Applications/AirSCP.app/Contents/MacOS/AirSCP --mcp` (any MCP client: that program with `--mcp`, over stdio). Or the Claude Code plugin: `/plugin marketplace add kleash/airscp`, then `/plugin install airscp@airscp`. An MCP client loads a new server at its next start; until then the same tools run from a shell: `/Applications/AirSCP.app/Contents/MacOS/AirSCP --agent snapshot` (`--agent guide` works before AirSCP is open).
- Driving it: `snapshot` → one action (`menu`, `press`, `set`, `select`, `drop`) → `wait` → `snapshot`. AirSCP's questions (Trust, passwords, Replace, Delete) come back as a `sheet` to answer. The `guide` tool has every tool and a recipe per feature. Agents never see saved passwords, but can type one they were given into AirSCP's password question (`set id=prompt.answer value=…`; from a shell, `value=-` with the password on standard input).

Every page of AirSCP Help (https://kleash.github.io/airscp/), then the agent guide.


---

Source: https://kleash.github.io/airscp/

# AirSCP Help

AirSCP is a Mac app for your servers. You save your servers once. Then you click to connect, and you drag files between
your Mac and the server. AirSCP also opens Windows desktops (Remote Desktop), shows what a Linux server is doing, and
opens tunnels. You don't need to type commands.

(Picture: The AirSCP window: saved servers on the left, files on this Mac and on a server side by side, and transfers at the bottom)

## Start here

- [Install AirSCP](https://kleash.github.io/airscp/getting-started/install.html)
- [Connect to your first server](https://kleash.github.io/airscp/getting-started/connect-your-first-server.html)
- [Copy your first files](https://kleash.github.io/airscp/getting-started/copy-your-first-files.html)
- [Find your way around the window](https://kleash.github.io/airscp/getting-started/the-window.html)

## Find a task

| I want to… | Read |
|---|---|
| Add a server | [Add a server](https://kleash.github.io/airscp/connecting/add-a-host.html) |
| Use my ~/.ssh/config | [Import hosts from ~/.ssh/config](https://kleash.github.io/airscp/connecting/import-from-ssh-config.html) |
| Reach a server behind another server | [Connect through a jump host](https://kleash.github.io/airscp/connecting/jump-hosts.html) |
| Upload or download files | [Copy files](https://kleash.github.io/airscp/files/copy-files.html) |
| Upload a whole folder | [Upload a folder](https://kleash.github.io/airscp/files/upload-a-folder.html) |
| Make two folders the same | [Synchronize two folders](https://kleash.github.io/airscp/synchronize.html) |
| Find a file on a server | [Find files on a server](https://kleash.github.io/airscp/find.html) |
| Free up disk space | [See what takes the room on a disk](https://kleash.github.io/airscp/disk-usage.html) |
| Work on a Windows computer | [Remote Desktop (Windows)](https://kleash.github.io/airscp/remote-desktop/) |
| Open Amazon S3 or similar storage | [S3 storage](https://kleash.github.io/airscp/s3/) |
| See CPU, memory and processes | [Watch a Linux server](https://kleash.github.io/airscp/monitor.html) |
| Reach a database behind a server | [Open a tunnel](https://kleash.github.io/airscp/tunnels.html) |
| Log in without a password | [Make a new key pair](https://kleash.github.io/airscp/keys/new-key-pair.html) |
| Let an AI agent use AirSCP | [AI agents (MCP)](https://kleash.github.io/airscp/ai-agents.html) |
| Fix a problem | [Troubleshooting](https://kleash.github.io/airscp/troubleshooting.html) |

## Help inside the app

- Hover over any button, field or menu item. A short line says what it does.
- A sheet with several choices has a small **?** button. It opens the page about that sheet.
- **Help ▸ AirSCP Tips** shows short tips, even without the internet.
- **Help ▸ Report a Problem** opens a short form on GitHub.


---

Source: https://kleash.github.io/airscp/getting-started/

# Getting started

New to AirSCP? These four short pages take you from installing the app to copying your first files.

1. [Install AirSCP](https://kleash.github.io/airscp/getting-started/install.html)
2. [Connect to your first server](https://kleash.github.io/airscp/getting-started/connect-your-first-server.html)
3. [Copy your first files](https://kleash.github.io/airscp/getting-started/copy-your-first-files.html)
4. [Find your way around the window](https://kleash.github.io/airscp/getting-started/the-window.html)

The first time you open AirSCP, a welcome sheet helps you start. You can open it again any time: **Help ▸ Welcome to
AirSCP…**.

(Picture: The Welcome to AirSCP sheet with Import from ~/.ssh/config, New Host and New Remote Desktop buttons and three tips)

Short tips are always one click away, even without the internet: **Help ▸ AirSCP Tips**.

(Picture: The AirSCP Tips window with tips about hosts, files and transfers)

## Words used in this help

- **Host** or **server**: a computer you log in to over SSH. AirSCP saves each one in the sidebar.
- **This Mac**: the files on your own Mac.
- **Remote Desktop** or **desktop**: a Windows computer you open in AirSCP's window.
- **Sheet**: a small window that slides over AirSCP's window and asks something.


---

Source: https://kleash.github.io/airscp/getting-started/install.html

# Install AirSCP

AirSCP runs on macOS 13.1 or later, on Apple silicon and Intel Macs. You need nothing else: AirSCP uses the ssh tools
that come with macOS.

## Steps

1. Install with [Homebrew](https://brew.sh):

   ```sh
   brew install --cask kleash/tap/airscp
   ```

   Or download the newest AirSCP zip file from the
   [Releases page](https://github.com/kleash/airscp/releases), open it, and drag **AirSCP** into your
   **Applications** folder.
2. Open **AirSCP** from your Applications folder or with Spotlight. AirSCP is signed and notarized by Apple, so macOS
   opens it after asking once whether you want to open an app downloaded from the internet: click **Open**.
3. The **Welcome to AirSCP** sheet opens. Choose what you want to do first:
   - **Import from ~/.ssh/config…** if you already use ssh in Terminal.
   - **New Host…** to add one server.
   - **New Remote Desktop…** to add a Windows computer.
   - **Start** to look around first.

(Picture: The welcome sheet)

## The App Store version

AirSCP also comes from the Mac App Store. It is the same app, but Apple's sandbox keeps it to what you allow, so a
few things work differently. Homebrew or the Releases page give you the version without these differences.

(Picture: The App Store version's welcome sheet, with Give Access to Your SSH Folder…)

| In the App Store version | Do this instead |
|---|---|
| AirSCP sees your SSH folder (`~/.ssh`) only after you allow it. | Click **Give Access to Your SSH Folder…** in the welcome sheet, or **Choose…** next to **SSH folder** in **Settings ▸ Keys**. Until then AirSCP keeps its own keys and known hosts. |
| **This Mac**'s pane opens a folder only after you allow it (your Downloads folder is always open). | When AirSCP asks, click **Allow**. Choose your home folder to allow everything in it. |
| **Open Terminal**, **Open Terminal Here** and **Run in Terminal** can't open Terminal or iTerm. | They use the host's [Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html) in AirSCP: at an empty prompt AirSCP types the `cd` or the command there, else it opens a new tab. |
| **Import from WinSCP…** reads only the files you choose. | Choose `WinSCP.ini` and its `.ppk` keys together. |
| **Import from ~/.aws…** reads your AWS folder only after you allow it. | When AirSCP asks, choose the `.aws` folder in your home folder and click **Allow**. |
| Your hosts from the Homebrew version aren't there. | In that version: **File ▸ Export Hosts…**. In this one: **File ▸ Import Hosts…**. |
| ssh uses only keys and configs in folders you allow, and not another app's ssh agent (a password manager's, for example). | Allow the folder that has them. For another app's agent, use the Homebrew version. |
| `AirSCP --agent … --out file.png` can't save outside AirSCP's own folder. | Use `--out -` and send the picture where you want it, or let your MCP client take it. |

## Tips

- AirSCP has no account and no sign-up. Your hosts stay on your Mac.
- The welcome sheet comes only once. Open it again with **Help ▸ Welcome to AirSCP…**.
- Short tips are always in **Help ▸ AirSCP Tips**.

## If something goes wrong

- **macOS asks whether AirSCP may use your Keychain.** This can happen the first time AirSCP reads a saved password. Choose
  **Always Allow**. AirSCP waits until you answer.
- **macOS asks whether AirSCP may find devices on your local network.** This is for Remote Desktop and servers on your
  network. Choose **Allow**.
- More: [Troubleshooting](https://kleash.github.io/airscp/troubleshooting.html).


---

Source: https://kleash.github.io/airscp/getting-started/connect-your-first-server.html

# Connect to your first server

Save a server once, then connect with one click. You need the server's address and your user name on it. Your server
admin or hosting company gives you these.

## Steps

1. Choose **File ▸ New Host…** (or click **+** in the toolbar).
2. Type the server's **Address**, for example `web-01.example.com` or `192.168.1.20`.
3. Type your **User name** on the server.
4. Under **Log in with**, choose your key, or **Password**. Not sure? Leave the default: it tries the keys in `~/.ssh`.
5. Click **Add**. The server appears in the sidebar.

   (Picture: The New Host sheet with a name, an address, a user name and a key)

6. Double-click the server in the sidebar (or select it and press <kbd>⌘K</kbd>).
7. The first time, AirSCP shows the server's key fingerprint and asks **Trust “…”?**. Click **Trust** if it is the
   server you expect. Read more in [Trust a server the first time](https://kleash.github.io/airscp/connecting/trust-a-server.html).

   (Picture: The Trust sheet with the server's key fingerprint)

8. If the server asks for a password, type it. Tick **Remember in Keychain** if you don't want to type it again.

Now you see your Mac's files on the left and the server's files on the right.

(Picture: Connected: this Mac on the left, the server's folder on the right)

## Tips

- Only the address is required. Everything else has a sensible default.
- **Test Connection** in the sheet logs in once, without saving, so you can check your settings.
- Behind a bastion? See [Connect through a jump host](https://kleash.github.io/airscp/connecting/jump-hosts.html).

## If something goes wrong

- **“Can't connect”**: check the address and the port. The message says what went wrong, and **Details** shows ssh's
  own words.
- **The password is not accepted**: check the user name in the host's settings (**Host ▸ Edit…**).
- More: [Troubleshooting](https://kleash.github.io/airscp/troubleshooting.html).


---

Source: https://kleash.github.io/airscp/getting-started/copy-your-first-files.html

# Copy your first files

Copy files between your Mac and a server by dragging them, like in Finder.

## Steps

1. Connect to the server ([how](https://kleash.github.io/airscp/getting-started/connect-your-first-server.html)).
2. In the left pane (**This Mac**), open the folder with your files.
3. In the right pane (the server), open the folder where the files should go.
4. Drag the files from the left pane to the right pane. That uploads them.
5. To download, drag files from the right pane to the left pane, or onto your Desktop.

The copies run in the **Transfers** list at the bottom of the window. You can keep working meanwhile.

(Picture: Files being uploaded: the Transfers list shows one running, one paused and one done)

## Other ways to copy

- Select files and click **Upload** (under the left pane) or **Download** (under the right pane).
- Drag files from Finder onto the server's pane.
- **Edit ▸ Copy** and **Edit ▸ Paste** work too.

## Tips

- A name that exists already? AirSCP asks: **Replace**, **Keep Both** or **Skip**. See
  [When a file already exists](https://kleash.github.io/airscp/files/replace-or-keep-both.html).
- A whole folder goes as one stream. See [Upload a folder](https://kleash.github.io/airscp/files/upload-a-folder.html).
- More about the queue: [Transfers and the queue](https://kleash.github.io/airscp/transfers/).


---

Source: https://kleash.github.io/airscp/getting-started/the-window.html

# Find your way around the window

AirSCP has one main window. Here is what each part does.

(Picture: The main window with its sidebar, toolbar, tabs, two file panes and the Transfers list)

## The sidebar (left)

- **Connected**: the servers and desktops that are connected now. <kbd>⌘1</kbd> to <kbd>⌘9</kbd> switch between them.
  A dot shows the state, and a number shows transfers that are waiting or running.
- **Hosts**, and your groups: all your saved servers. A server that goes through another server says so under its name,
  for example “via bastion”.
- **Remote Desktop**: your Windows computers.
- **Proxies** (at the bottom): HTTP proxies, if your network needs one. Most people need none.

## The toolbar (top)

From left to right: **+** (add a host, a Remote Desktop or a group), **Connect** (<kbd>⌘K</kbd>), **Open Terminal**
(<kbd>⌘T</kbd>), **Run Command** (<kbd>⇧⌘R</kbd>), **Command Log** (<kbd>⌥⌘L</kbd>), **Disconnect** (<kbd>⌘E</kbd>) and
**Search Hosts**.

## The top of a server

The server's name and state (**Connected**, **Not connected**…), its user, address and port, the route through jump
hosts and proxies, and its keep-alive. For a connected Linux server, three small boxes show its **CPU**, **memory** and
**disk** at a glance; the [Monitor](https://kleash.github.io/airscp/monitor.html) tab has the details.

## The tabs

- **Files**: two panes. The left pane is this Mac (or another server), the right pane is the selected server.
- **Monitor**: CPU, memory, disks, processes and ports of a Linux server. See [Monitor](https://kleash.github.io/airscp/monitor.html).
- **Tunnels**: port forwards through the connection. See [Tunnels](https://kleash.github.io/airscp/tunnels.html).

## The Transfers list (bottom)

Every upload and download of every server. See [Transfers and the queue](https://kleash.github.io/airscp/transfers/). Hide it with
**View ▸ Hide Transfers**.

## Tips

- Every button and menu item explains itself. Hover over it for a moment.
- **View ▸ Hide Sidebar** (<kbd>⌃⌘S</kbd>) gives the files more room.
- Closing the window keeps your connections. Click AirSCP in the Dock, or press <kbd>⌘0</kbd>, to bring it back.
- The Dock icon shows how many transfers are waiting or running.


---

Source: https://kleash.github.io/airscp/connecting/

# Connecting

How to save your servers and log in to them: with a key, a password, through a jump host or a proxy.

(Picture: The sidebar with hosts in groups, a host that goes via a bastion and one via a proxy)

## Pages

- [Add a server](https://kleash.github.io/airscp/connecting/add-a-host.html): the host settings, one by one.
- [Import hosts from ~/.ssh/config](https://kleash.github.io/airscp/connecting/import-from-ssh-config.html): reuse what you already have.
- [Import your sites from WinSCP](https://kleash.github.io/airscp/connecting/import-from-winscp.html): sites, keys, tunnels and proxies from Windows.
- [Log in with a password](https://kleash.github.io/airscp/connecting/log-in-with-a-password.html), and with two-factor codes.
- [Log in with a key](https://kleash.github.io/airscp/connecting/log-in-with-a-key.html): no password to type.
- [Trust a server the first time](https://kleash.github.io/airscp/connecting/trust-a-server.html): what the fingerprint question means.
- [Connect through a jump host](https://kleash.github.io/airscp/connecting/jump-hosts.html): servers behind a bastion.
- [Connect through a proxy](https://kleash.github.io/airscp/connecting/proxies.html): networks that only go out through an HTTP or SOCKS5 proxy.
- [Extra ssh settings](https://kleash.github.io/airscp/connecting/extra-ssh-settings.html): one ssh option per line, with examples.
- [Self-signed certificates and corporate networks](https://kleash.github.io/airscp/connecting/self-signed-certificates.html).
- [Stay connected](https://kleash.github.io/airscp/connecting/stay-connected.html): keep-alive and automatic reconnect.
- [Groups, colours and search](https://kleash.github.io/airscp/connecting/organise-hosts.html).
- [Move your hosts to another Mac](https://kleash.github.io/airscp/connecting/move-to-another-mac.html).
- [Server information, change your password, links](https://kleash.github.io/airscp/connecting/server-info.html).
- [Browse and copy files as root (sudo)](https://kleash.github.io/airscp/connecting/browse-as-root.html).


---

Source: https://kleash.github.io/airscp/connecting/add-a-host.html

# Add a server

A host is a server you log in to over SSH. Save it once, and AirSCP connects with one click. Only the address is
required: the rest has sensible defaults.

## Steps

1. Choose **File ▸ New Host…** (<kbd>⌘N</kbd>), or click **+** in the toolbar and choose **New Host…**.
2. Fill in the fields you need (see the table below).
3. Click **Test Connection** to log in once without saving (optional).
4. Click **Add**.

(Picture: The New Host sheet)

| Field | What to type |
|---|---|
| **Name** | A short name for the sidebar, for example `web-01`. Optional. |
| **Address** | The server's host name or IP address. An alias from your `~/.ssh/config` works too. |
| **Port** | Leave it empty for 22, the usual SSH port. |
| **User name** | Your account on the server. Empty: the same as on your Mac (or what your ssh config says). |
| **Log in with** | Your keys in `~/.ssh` (the default), one key, a key file elsewhere, or **Password**. See [Log in with a key](https://kleash.github.io/airscp/connecting/log-in-with-a-key.html) and [Log in with a password](https://kleash.github.io/airscp/connecting/log-in-with-a-password.html). |
| **Connect through** | Another saved host to go through first, for servers behind a bastion. See [Connect through a jump host](https://kleash.github.io/airscp/connecting/jump-hosts.html). |
| **Start in folder** | The folder to show after connecting. Empty: your home folder. |
| **Group** | A group to sort the host under in the sidebar. |

## Advanced

Click **Advanced** for settings most people never change.

(Picture: The Advanced part of the host sheet)

| Setting | What it does |
|---|---|
| **Proxy** | Only when your network reaches servers through a proxy. See [Connect through a proxy](https://kleash.github.io/airscp/connecting/proxies.html). |
| **Keep-alive every** | How often AirSCP checks that the connection still works: 15 seconds by default. The connection counts as lost after 3 unanswered checks. |
| **Reconnect automatically** | On by default. When the connection drops, AirSCP connects again by itself. See [Stay connected](https://kleash.github.io/airscp/connecting/stay-connected.html). |
| **Let the server use my ssh agent** | Off by default. Turn it on only if you use your keys from that server to reach others (agent forwarding). |
| **Server key** | How AirSCP checks the server's identity. **Ask (default)** is right for most people. See [Self-signed certificates and corporate networks](https://kleash.github.io/airscp/connecting/self-signed-certificates.html). |
| **Other ssh options** | Extra ssh settings, one per line. See [Extra ssh settings](https://kleash.github.io/airscp/connecting/extra-ssh-settings.html). |

## Change, copy or delete a host

- **Host ▸ Edit…** changes the selected host. A connected host uses the changes the next time it connects.
- **Host ▸ Duplicate** makes a copy, with its tunnels and saved password.
- **Host ▸ Delete…** forgets the host and its saved password. AirSCP asks first.
- Right-click a host in the sidebar for the same commands.

## Tips

- The **?** button in the sheet opens this page.
- Copy the ssh command for a host: **Host ▸ Copy ssh Command** (<kbd>⇧⌘C</kbd>). Paste it into any terminal.
- A host that other hosts or desktops go through can't be deleted until they stop using it.


---

Source: https://kleash.github.io/airscp/connecting/import-from-ssh-config.html

# Import hosts from ~/.ssh/config

Already use ssh in Terminal? AirSCP can make a host for each alias in your `~/.ssh/config`. ssh keeps reading their
settings from your config, so later changes there apply in AirSCP too.

## Steps

1. Choose **File ▸ Import from ~/.ssh/config…** (the welcome sheet has this button too).
2. AirSCP lists the aliases from the `Host` lines, with the user and address ssh makes of each one.
3. Tick the ones you want. Aliases that are in AirSCP already are greyed out.
4. Click **Import**.

(Picture: The Import from ~/.ssh/config sheet with a list of aliases)

## Tips

- AirSCP also reads the files that your config's `Include` lines name.
- Patterns such as `Host *` or `Host *.example.com` are skipped: they aren't one server.
- AirSCP never changes your `~/.ssh/config`.

## If something goes wrong

- **“No hosts found in ~/.ssh/config”**: your config has no `Host` lines with plain names. Add a host with
  **File ▸ New Host…** instead.


---

Source: https://kleash.github.io/airscp/connecting/log-in-with-a-password.html

# Log in with a password

Some servers ask for a password, and some for a code from an app as well (two-factor). AirSCP asks these questions in
its own window and names the host they are for.

## Steps

1. Select the host and choose **Host ▸ Edit…**.
2. Set **Log in with** to **Password**. You can type the password there, or leave it empty to be asked.
3. Click **Save**, then connect.
4. When AirSCP asks, type the password. Tick **Remember in Keychain** to save it.

(Picture: The password question for a host, with Remember in Keychain)

## Two-factor codes

If the server asks for a verification code after the key or password, AirSCP shows ssh's question, for example
`Verification code:`. Type the code from your authenticator app and click **OK**.

## Tips

- A saved password is tried once, silently. If the server refuses it, AirSCP asks again.
- A question asked again says “That password wasn't accepted”, so you know the first try failed.
- Passwords are saved in your Mac's login Keychain, never in a file.
- With a key you don't need a password at all. See [Log in with a key](https://kleash.github.io/airscp/connecting/log-in-with-a-key.html).

## If something goes wrong

- **“The server didn't accept the user name or password”**: check the **User name** in the host's settings, then try
  the password again.
- **The question doesn't come back after a wrong password**: some servers close the connection after a few tries.
  Click **Reconnect**.


---

Source: https://kleash.github.io/airscp/connecting/log-in-with-a-key.html

# Log in with a key

A key pair lets you log in without typing a password. The private key stays on your Mac; the public key goes on the
server.

## Steps

1. Select the host and choose **Host ▸ Edit…**.
2. Open **Log in with** and choose:
   - **Keys in ~/.ssh and the ssh agent (default)**: ssh tries your usual keys. Fine for most people.
   - **A key from the list**: only that key is tried. Each one shows its name, type and comment.
   - **Choose a Key File…**: a key that is somewhere else. A PuTTY key (`.ppk`) is imported first.
   - **Generate New Key…**: makes a new key for this host. See [Make a new key pair](https://kleash.github.io/airscp/keys/new-key-pair.html).
3. Click **Save**, then connect.

(Picture: The host sheet with a key chosen under Log in with)

## Put the public key on the server

The server must know your public key. If it doesn't yet, use **Window ▸ Keys ▸ Install on Host…**: AirSCP logs in once
with your password and adds the key. See [Put your key on a server](https://kleash.github.io/airscp/keys/install-a-key.html).

## Tips

- A key with a passphrase: AirSCP asks for it when connecting. **Add to Agent** in the Keys window can keep it in your
  Keychain, so you type it once.
- A key file that no longer exists shows in red as “(missing)”, and the host gets a warning in the sidebar.
- “Too many authentication failures”? Choose one key instead of the default, or add `IdentitiesOnly=yes` in
  [Extra ssh settings](https://kleash.github.io/airscp/connecting/extra-ssh-settings.html).


---

Source: https://kleash.github.io/airscp/connecting/trust-a-server.html

# Trust a server the first time

The first time you connect to a server, AirSCP shows the server's key fingerprint and asks **Trust “…”?**. This
protects you: if someone pretends to be your server later, its key won't match, and ssh stops.

## Steps

1. Connect to the server.
2. Compare the fingerprint (it starts with `SHA256:`) with the one your server admin or hosting company gave you.
3. If it matches, click **Trust**. ssh remembers the key (in `known_hosts`) and doesn't ask again.
4. If you don't know, or it doesn't match, click **Cancel**.

(Picture: The Trust sheet with the server's key fingerprint)

## When the key has changed

If a server's key is different from the one ssh remembered, AirSCP explains the risk and does not connect. This happens
when a server is reinstalled, or when someone is in the middle of your connection. Ask the server's admin. If the change
is expected, AirSCP offers to remove the old key and connect again.

## Tips

- A test machine or a lab you can't check? In the host's settings, **Advanced ▸ Server key** can trust new servers
  automatically. A changed key is still refused. See [Self-signed certificates and corporate networks](https://kleash.github.io/airscp/connecting/self-signed-certificates.html).
- Jump hosts ask too: you trust each server once.

## If something goes wrong

- **“The server's host key was not accepted, so AirSCP didn't connect”**: you clicked Cancel. Connect again and click
  **Trust** if the fingerprint is the one you expect.


---

Source: https://kleash.github.io/airscp/connecting/jump-hosts.html

# Connect through a jump host

Some servers can't be reached from your Mac directly: you first log in to another server, often called a **bastion** or
**jump host**. AirSCP does both steps for you (this is ssh's `ProxyJump`).

## Steps

1. Save the bastion as a host first ([Add a server](https://kleash.github.io/airscp/connecting/add-a-host.html)).
2. Add the inner server: **File ▸ New Host…**. For its **Address**, use the name or IP address that the *bastion* uses
   to reach it.
3. Set **Connect through** to the bastion.
4. Click **Add** and connect. AirSCP asks the bastion's questions first (trust, password), one sheet each.

(Picture: A host sheet with Connect through set to bastion)

The sidebar shows the route under the host's name, for example **via bastion**. Hover over the host to see each hop in
full.

(Picture: The sidebar: db-01 via bastion, partner-sftp via proxy Office proxy)

## Tips

- One hop is supported: Mac → bastion → server.
- The bastion can use a proxy, so the full route can be Mac → proxy → bastion → server.
- Take your time with the bastion's questions: the 15-second timeout is only for reaching a server directly.
- A Windows computer can go through an SSH host too. See [Remote Desktop (Windows)](https://kleash.github.io/airscp/remote-desktop/).

## If something goes wrong

- The route line is red: the jump host was deleted. Edit the host and choose another one.
- **“The server can't be reached from this network”**: check that the inner server's address is the one the bastion uses.


---

Source: https://kleash.github.io/airscp/connecting/proxies.html

# Connect through a proxy

Some company networks reach the internet only through a proxy. AirSCP can send a host's connection through an HTTP
proxy (HTTP CONNECT) or a SOCKS5 proxy, with or without a user name and password. Most people need none.

## Steps

1. Choose **Host ▸ Proxies…** (or click **Proxies** at the bottom of the sidebar).
2. Click **Add Proxy…**. Choose its **Type** (**HTTP** or **SOCKS5**), then type its **Name**, **Address** and **Port**.
   Your network admin knows these.
3. If the proxy needs a login, type the **User name**. The password field appears then; leave it empty to be asked.
4. Click **Add**, then **Done**.
5. Edit the host (**Host ▸ Edit…**), click **Advanced**, and choose the proxy under **Proxy**.

(Picture: The Proxies sheet with one proxy)

(Picture: The proxy sheet with name, address, port and user name)

## Tips

- A host that connects through a jump host uses the jump host's proxy: the proxy is only on the way to the jump
  host.
- AirSCP logs in to an HTTP proxy the way it asks: Basic, or Digest (MD5 or SHA-256). With Digest, your password never
  goes over the network.
- A **SOCKS5** proxy is often on port 1080, or is an `ssh -D` tunnel. With a user name, AirSCP logs in with it.
- **Copy ssh Command** works for a host behind a proxy without a login: the command reaches the proxy with macOS's
  `nc`.
- The sidebar shows **via proxy …** under a host that goes through a proxy.
- The proxy's password is kept in your Keychain. A password the proxy refuses is forgotten, so you are asked again.
- A proxy that hosts still use can't be removed.

## If something goes wrong

- **“The proxy rejected the user name or password”**: edit the proxy and check the user name; connect again to type
  the password.
- SOCKS4 proxies aren't supported: only HTTP proxies that allow CONNECT, and SOCKS5 proxies.


---

Source: https://kleash.github.io/airscp/connecting/extra-ssh-settings.html

# Extra ssh settings

Sometimes a server needs an ssh setting that AirSCP has no field for. Add it under **Other ssh options**, one per line,
as `Name=value`. Leave it empty unless you need one.

## Steps

1. Select the host and choose **Host ▸ Edit…**, then click **Advanced**.
2. Under **Other ssh options**, type one setting per line, for example `ConnectTimeout=10`.
3. Or use **Add Common Option…**: it adds a line for you and says when you'd use it.
4. Click **Save**.

(Picture: Other ssh options with two lines and the Add Common Option menu)

AirSCP checks each line as you type, with `ssh -G` (which connects nowhere). A wrong line is shown in red with ssh's
reason, and **Save** waits until it is fixed.

## Common options

| Option | When you'd use it |
|---|---|
| `Compression=yes` | Faster on slow links for text and logs; slower on fast networks. |
| `ConnectTimeout=10` | Give up after 10 seconds instead of waiting long for a server that is down. |
| `IdentitiesOnly=yes` | Try only the chosen key. Fixes “Too many authentication failures”. |
| `PubkeyAcceptedAlgorithms=+ssh-rsa` | Old servers that only know RSA keys. |
| `HostKeyAlgorithms=+ssh-rsa` | Old servers whose own key is RSA. |
| `KexAlgorithms=+diffie-hellman-group14-sha1` | Very old servers (“no matching key exchange”). |
| `AddressFamily=inet` | Use IPv4 only, when IPv6 hangs. |
| `StrictHostKeyChecking=accept-new` | Trust a new server's key automatically, but still warn when it changes. The **Server key** setting does this too. |
| `SetEnv LANG=en_US.UTF-8` | Fix garbled characters in file names. |
| `IPQoS=throughput` | Steadier big transfers on some Wi-Fi networks and routers. |
| `LogLevel=ERROR` | Hide the server's banner text in the command log. |

## Tips

- Settings that AirSCP has a field for (port, user, key, jump host, proxy) belong in those fields.
- Some options can't be changed here, because AirSCP runs them itself (for example `ControlMaster`, `ControlPath`,
  `ControlPersist`, `RemoteCommand`). The red line says why.
- Your `~/.ssh/config` still applies: use it for settings you share with Terminal.


---

Source: https://kleash.github.io/airscp/connecting/self-signed-certificates.html

# Self-signed certificates and corporate networks

Company servers often use their own (self-signed) certificates, so AirSCP asks about them every time it meets a new
one. You can tell AirSCP how to check each server. The safe choice, **Ask**, is the default, and a relaxed choice is
always visible.

## SSH servers: Server key

Edit the host (**Host ▸ Edit…**), click **Advanced**, and choose **Server key**:

| Choice | What happens |
|---|---|
| **Ask (default)** | AirSCP shows a new server's key fingerprint for you to trust. A changed key is refused. |
| **Trust new servers automatically** | A new server's key is trusted without asking. A changed key is still refused (ssh's `StrictHostKeyChecking=accept-new`). |
| **Don't check (insecure)** | No check, and the key isn't remembered. Anyone on the network could pretend to be this server and see what you send, passwords too. Only for test machines on a network you trust. |

(Picture: Server key set to Don't check, with a red warning under it)

## Windows desktops: Server certificate

Edit the desktop (**Host ▸ Edit…**), click **Advanced**, and choose **Server certificate**:

| Choice | What happens |
|---|---|
| **Ask (default)** | AirSCP shows a certificate it doesn't know yet, with its fingerprint: **Always Trust**, **Trust Once** or **Cancel**. It warns when a trusted certificate changes. |
| **Trust automatically** | The first certificate is trusted and remembered without a question. A changed one still warns. |
| **Don't check (insecure)** | Never asks. Anyone on the network could pretend to be this computer. |
| **Trust my company's certificate authority** | Choose your company's certificate authority file (`.pem` or `.cer`, from your IT team). Certificates it signed for the name you connect to are trusted; any other is asked about. This is the best fix for company servers. |

(Picture: Server certificate set to Trust my company's certificate authority, with the file chosen)

## Defaults for new hosts and desktops

**AirSCP ▸ Settings… ▸ Security** sets the choice for hosts and desktops you add later. Existing ones keep theirs.

## Always visible

A host or desktop set to **Don't check** shows an orange shield in the sidebar and above its files or desktop. Hover over
the shield to read why it is there.

## Tips

- Ask your IT team for the company certificate authority file. It is the same file browsers use for internal sites.
- The **?** button in the certificate question opens this page.


---

Source: https://kleash.github.io/airscp/connecting/stay-connected.html

# Stay connected

Wi-Fi drops, a Mac goes to sleep, a VPN restarts. AirSCP notices, connects again by itself, and continues your
transfers.

## What AirSCP does

- **Keep-alive**: every 15 seconds AirSCP checks that the connection still works. After 3 unanswered checks it counts
  as lost. Change the time per host: **Host ▸ Edit… ▸ Advanced ▸ Keep-alive every**.
- **Reconnect automatically** (on by default): when a connection drops, AirSCP tries again after 2, 5, 15 and 30
  seconds, then every minute for up to 10 minutes. It also tries at once when the network comes back or the Mac wakes.
- **Transfers continue**: transfers that failed because the connection was lost run again after reconnecting. A single
  file continues where it stopped. See [When the connection drops during a transfer](https://kleash.github.io/airscp/transfers/resume.html).

(Picture: The banner: The connection was lost. Reconnecting… next try in a few seconds, with Cancel and Reconnect Now)

## Steps

- To stop the tries, click **Cancel** in the banner.
- To try now, click **Reconnect Now**.
- To turn it off for one host, edit the host and untick **Reconnect automatically**.

## Tips

- Reconnecting never asks you anything. If logging in needs an answer (a password that isn't saved, a passphrase, a
  verification code, a new server key), AirSCP stops and shows **Disconnected** with a **Reconnect** button.
- After **Host ▸ Disconnect**, or when AirSCP stops trying, the server's pane shows no files: they could be out of
  date. Click **Reconnect** there to connect again and see the same folder.
- Tunnels that were on come back on when AirSCP reconnects by itself. After you click **Reconnect**, switch them on
  again in the **Tunnels** tab.
- A connected host stays connected while you look at another host.


---

Source: https://kleash.github.io/airscp/connecting/organise-hosts.html

# Groups, colours and search

Many servers? Sort them into groups, give them colours, and find them by typing.

## Steps

- **Make a group**: **File ▸ New Group…**, type a name, click **Create**. Then choose the group in a host's settings
  (**Group**).
- **Rename or delete a group**: **Host ▸ Rename Group** or **Host ▸ Delete Group**, or right-click the group's heading.
  Deleting a group keeps its hosts.
- **Colour a host**: **Host ▸ Colour Tag**, or right-click the host.
- **Find a host**: type in **Search Hosts** in the toolbar. It matches names, addresses, users, jump hosts and proxies.

(Picture: The sidebar with groups Internal and Production and coloured hosts)

## Tips

- Group names are unique.
- The **Connected** section at the top lists what is connected now, in the order you connected. <kbd>⌘1</kbd> to
  <kbd>⌘9</kbd> switch between them.
- Search also finds a host by the address its row shows, for example `dev@10.0.0.5:2222`.


---

Source: https://kleash.github.io/airscp/connecting/move-to-another-mac.html

# Move your hosts to another Mac

Export your hosts, groups, proxies and Remote Desktop entries to a file, and import that file on another Mac.

## Steps

1. On the first Mac, choose **File ▸ Export Hosts…** and save the file.
2. Copy the file to the other Mac (AirDrop, a USB stick, a cloud folder).
3. On the other Mac, choose **File ▸ Import Hosts…** and pick the file.
4. AirSCP says how many hosts it imported.

(Picture: The sidebar after importing: hosts in their groups)

## Tips

- Passwords are not in the file: they stay in the first Mac's Keychain. AirSCP asks for them when you connect.
- Key files in your home folder are saved as `~/…`, so they work when the other Mac has the same keys in the same place.
  Copy your keys yourself; AirSCP never puts private keys in the export.
- Importing a file again updates the hosts it imported before, instead of adding copies.
- A host's extra ssh settings can run a program on your Mac when it connects (`ProxyCommand`, `LocalCommand`). When a
  file has such settings, AirSCP lists them and asks first: **Leave Them Out** imports the hosts without them. Keep
  them only if you trust whoever made the file.


---

Source: https://kleash.github.io/airscp/connecting/import-from-winscp.html

# Import your sites from WinSCP

Coming from WinSCP on Windows? AirSCP can make a host for each of your WinSCP sites, with its folder, its key, its
tunnel (as a jump host) and its proxy.

## Steps

1. In WinSCP on the PC, choose **Tools ▸ Export/Backup Configuration…** and save **WinSCP.ini**.
2. Copy WinSCP.ini to this Mac. Put the PuTTY keys (.ppk files) your sites use in the same folder.
3. In AirSCP, choose **File ▸ Import from WinSCP…** and pick WinSCP.ini.
4. AirSCP says how many hosts it made, and what it left out.

## What comes over

- Each SFTP or SCP site becomes a host: address, port, user name and the folder it opens in.
- A folder of sites becomes a group. A site in a folder in a folder goes in a group such as “Work/Web”.
- **Tunnel** settings become a jump host, shared by the sites that use it. See [Connect through a jump host](https://kleash.github.io/airscp/connecting/jump-hosts.html).
  A site that also goes through a proxy gets a jump host through that proxy (named “bastion via proxy”), so the
  proxy is never skipped. Hosts you already have are never changed.
- An HTTP or SOCKS5 proxy becomes a proxy. See [Connect through a proxy](https://kleash.github.io/airscp/connecting/proxies.html). Sites through SOCKS4 or a
  proxy WinSCP runs itself stay behind.
- A .ppk key without a passphrase becomes an OpenSSH key in your key folder (~/.ssh unless Settings names another),
  and the host logs in with it.

## What stays behind

- **Saved passwords**: AirSCP never reads them. It asks for a password when you connect, and can keep it in the
  Keychain.
- **FTP, WebDAV and S3 sites**: AirSCP connects over SSH only.
- **SOCKS4 proxies** and proxies that WinSCP runs itself: add those hosts by hand.
- A .ppk key **with a passphrase**: import it in **Window ▸ Keys**, then choose it in **Edit Host**.

## Tips

- Importing the same file again adds only the sites that are new.
- WinSCP keeps its settings in the Windows registry until you export them. **Tools ▸ Export/Backup Configuration…**
  always writes a WinSCP.ini that AirSCP can read.

## If something goes wrong

- **“No SSH sites in WinSCP.ini”**: the file has no SFTP or SCP sites. Check that you exported WinSCP's configuration,
  not a single site's URL.
- **“deploy.ppk isn't beside the file”**: copy that key into the folder that holds WinSCP.ini, then import again.


---

Source: https://kleash.github.io/airscp/connecting/server-info.html

# Server information, change your password, links

## Server information

1. Connect to the host.
2. Choose **Host ▸ Server Info…**.
3. You see:
   - **Server key**: the server's key type and SHA-256 fingerprint, as your Mac trusts it. Compare it with what your
     server's admin gives you.
   - **Software**, **Key exchange** and **Cipher**: what the server runs and how the connection is encrypted. These need
     **Help ▸ Turn On Debug Logging** before you connect.
   - **Can**: what AirSCP found the server can do (run commands, tar, zip, checksums…).
   - **Free space** in the folder the pane shows.
4. Click **Copy** to put it all on the clipboard, for a support request.

## Change your password on the server

1. Connect to the host.
2. Choose **Host ▸ Change Password…**. The Terminal tab opens and runs `passwd`.
3. Type your current password, then the new one twice, as `passwd` asks.
4. If AirSCP saved your old password, it offers to save the new one: type it once more and click **Save** (or
   **Forget It**, and the next connect asks).

AirSCP never reads the password back from your Keychain to do this.

## Links

- **Host ▸ Copy Link** copies a link like `sftp://deploy@web.example.com/var/www`: the host and the folder shown. It
  never holds a password.
- Opening an `sftp://` or `ssh://` link (in Safari, Mail or Terminal) opens it in AirSCP: the saved host with that
  address at that folder, or its Terminal tab for `ssh://`. For a server you haven't saved, **New Host…** opens filled
  in from the link.


---

Source: https://kleash.github.io/airscp/connecting/browse-as-root.html

# Browse and copy files as root (sudo)

Some files only root (or another user) may change: web server configs, other users' folders. AirSCP can browse,
change and copy files as that user, with `sudo`.

## Steps

1. Choose **Host ▸ Edit…**, then **Advanced**.
2. In **Browse and transfer as**, type the user, for example `root`.
3. Click **Save**, then connect.

From then on, listings, new folders, renames, deletes, permissions, uploads and downloads happen as that user. The
commands you type (**Run Command…**, snippets) and the **Terminal** tab stay yours.

## What the server needs

- `sudo` that lets your user become that user **without a password** (a `NOPASSWD` rule in `/etc/sudoers`), for
  example: `deploy ALL=(root) NOPASSWD: ALL`.
- OpenSSH's `sftp-server` program (most Linux servers have it; BusyBox-only systems don't).

When something is missing, connecting stops and says what, instead of browsing as your own user.

## Tips

- Files AirSCP makes this way belong to that user (root, say).
- Copies go with sftp for such a host (scp can't change user); folders still go as one stream where the server has tar.
- Use it only for the hosts that need it: everything you do there is done as root.


---

Source: https://kleash.github.io/airscp/files/

# Files

The **Files** tab has two panes. The left pane shows this Mac (or another connected server). The right pane shows the
selected server. Drag between them to copy.

(Picture: The Files tab: this Mac on the left, the server on the right)

## Pages

- [Browse a server's folders](https://kleash.github.io/airscp/files/browse.html): go to folders, filter, hidden files, columns, favourites.
- [Copy files](https://kleash.github.io/airscp/files/copy-files.html): upload and download.
- [Upload a folder](https://kleash.github.io/airscp/files/upload-a-folder.html): one stream, compress, leave out.
- [When a file already exists](https://kleash.github.io/airscp/files/replace-or-keep-both.html): Replace, Keep Both or Skip.
- [Copy between two servers](https://kleash.github.io/airscp/files/copy-between-servers.html).
- [Open and edit a server file](https://kleash.github.io/airscp/files/edit-files.html).
- [New folder, rename, duplicate, delete, Get Info](https://kleash.github.io/airscp/files/manage-files.html).
- [Change permissions](https://kleash.github.io/airscp/files/permissions.html).
- [Compress and extract on the server](https://kleash.github.io/airscp/files/compress-and-extract.html).
- [Select by pattern, compare folders, move, link](https://kleash.github.io/airscp/files/select-and-compare.html).

## Tips

- Right-click a file for everything you can do with it.
- A command that a server can't run is greyed out, and its tooltip says why (for example an account that allows file
  transfers only).


---

Source: https://kleash.github.io/airscp/files/browse.html

# Browse a server's folders

Move around a server's folders like in Finder.

## Steps

- **Open a folder**: double-click it, or select it and press <kbd>⌘↓</kbd> (**Go ▸ Open Selection**).
- **Go up**: the **↑** button, or <kbd>⌘↑</kbd> (**Go ▸ Enclosing Folder**).
- **Back and forward**: the arrow buttons, or <kbd>⌘[</kbd> and <kbd>⌘]</kbd>.
- **Home folder**: the house button, or <kbd>⇧⌘H</kbd>.
- **Type a path**: <kbd>⇧⌘G</kbd> (**Go ▸ Go to Folder…**). `~` means your home folder.
- **Click a folder in the path bar** under the buttons to jump there.
- **Filter**: type in **Filter by name** (or press <kbd>⌘F</kbd>) to show only matching names.
- **Hidden files**: the eye button, or <kbd>⇧⌘.</kbd>, shows names that start with a dot.
- **Refresh**: the circle arrow, or <kbd>⌘R</kbd>.

(Picture: The server pane with its path bar, buttons and filter field)

## Columns and sorting

- Click a column heading to sort by it. Click again to reverse.
- Right-click the headings (or **View ▸ Columns**) to show or hide columns: size, date modified, permissions, owner,
  group and kind.
- **Owner** and **Group** show names, as **Get Info** does. Point at one to see its number (user ID or group ID).
  Servers that allow only file transfers (sftp) show the names without numbers.
- Folders show “—” as their size. **View ▸ Calculate Folder Sizes** (the **Σ** button) works them out. **Settings** can
  do it always.

## Favourites

- **Go ▸ Add to Favourites** keeps the server folder you see, for that host.
- **Go ▸ Favourites** lists them: choose one to go there, or **Remove** one.
- When the other pane shows a folder on this Mac as you add a favourite, AirSCP remembers it too: choosing the
  favourite shows both folders again.
- **Go ▸ Other Pane's Folder** (<kbd>⌥⌘O</kbd>) shows the folder the other pane shows (this Mac, or the same server).

## Tips

- The status line under each pane shows the number of items, your selection and its size, and the free space.
- A folder your account can't read shows an error, not an empty list.
- Large folders list fast: 50,000 items in about a second on most Linux servers.


---

Source: https://kleash.github.io/airscp/files/copy-files.html

# Copy files

Upload files from your Mac to a server, or download them from a server to your Mac.

## Steps

**Upload**

1. Open the target folder in the server pane (right).
2. Drag files from the left pane, or from Finder, onto the server pane.
   Or select files in the left pane and click **Upload**.

**Download**

1. Open the target folder in the left pane, this Mac.
2. Drag files from the server pane to the left pane, or onto your Desktop or a Finder window.
   Or select them and click **Download**, or choose **File ▸ Download To…** to pick a folder.

(Picture: Uploads in the Transfers list: one running, one paused, one done)

The copies run in the **Transfers** list. See [Transfers and the queue](https://kleash.github.io/airscp/transfers/).

## Other ways

- **File ▸ Copy to Other Pane** copies the selection into the folder the other pane shows. Its name says where:
  “Upload to …”, “Download to …”.
- **Edit ▸ Copy** and **Edit ▸ Paste**. Files copied in Finder can be pasted into a server pane: they are uploaded.
- **File ▸ Upload…** chooses Mac files to upload.
- **File ▸ Upload Compressed** packs the selected Mac items into one stream and unpacks them on the server.
- **File ▸ Download as .tar.gz…**: see [Download as one archive](https://kleash.github.io/airscp/transfers/download-as-archive.html).

## Within one server

- Dragging inside one server **moves** the items. Hold <kbd>⌥</kbd> to copy instead.
- **Edit ▸ Cut** and **Edit ▸ Paste** move too.

## Tips

- Copies are safe: a file arrives under a temporary name and takes its real name only when it is complete. A cancelled
  copy never leaves a half file in place of the old one.
- A replaced server file keeps its permissions.
- **Settings ▸ Copied files keep their original date** keeps the files' dates (off by default).


---

Source: https://kleash.github.io/airscp/files/upload-a-folder.html

# Upload a folder

Copy a whole folder to a server. AirSCP sends each folder as one stream, which is much faster than file by file.

## Steps

1. Drag the folder onto the server pane (or select it and click **Upload**).
2. AirSCP asks before it copies: **Upload 1 folder to “…”?**
3. Optional: type names or patterns in **Leave out**, separated by commas, for example `*.log, node_modules, .git`.
   They stay behind wherever they are in the folder. AirSCP remembers this for the server.
4. Optional: tick **Compress during transfer**. It is faster on slow connections and for many small files, slower on
   fast ones.
5. Click **Upload**.

(Picture: The Upload sheet with Leave out and Compress during transfer)

Downloading a folder works the same way, with the same sheet.

## Tips

- `*`, `?` and `[ ]` work in Leave out: `*.psd` leaves out every Photoshop file.
- [Synchronize](https://kleash.github.io/airscp/synchronize.html) uses the same Leave out list for the server.
- 200 or more loose files at once get the same sheet, and go as one stream too.
- Symbolic links stay links.
- The **?** button in the sheet opens this page.

## If something goes wrong

- **“This server can't send folders as one stream”**: the server has no shell or no `tar` (for example an account that
  allows file transfers only). AirSCP copies the folder whole with scp instead, and Leave out can only skip the items
  you picked.
- **Names that differ only in case** (`README` and `readme`) can't sit side by side on a Mac disk. AirSCP says so when
  you download such a folder.


---

Source: https://kleash.github.io/airscp/files/replace-or-keep-both.html

# When a file already exists

When you copy a file to a folder that already has one with the same name, AirSCP asks what to do. It shows the size
and date of both, so you can decide.

## Steps

1. Read the line that compares them, for example
   `New: 75 bytes, 2 Oct 2026 at 4:30 PM · Existing: 75 bytes, 28 Sep 2026 at 10:15 AM`.
2. Choose:
   - **Replace**: the new file takes the old one's place.
   - **Replace If Newer**: the new file takes its place only if it is newer; otherwise it is skipped. With **Do the
     same for the other … conflicts** ticked, every newer file is copied and every older one skipped. Shown for two
     files whose dates AirSCP knows.
   - **Keep Both**: the new file gets a number, for example `index 2.html`.
   - **Skip**: the old file stays, and this one isn't copied.
   - **Cancel**: nothing more is copied.
3. Copying many files? Tick **Do the same for the other … conflicts** to answer once for all of them.

(Picture: The question: index.html already exists in www. Replace, Keep Both, Skip or Cancel)

## Tips

- AirSCP checks the folder as it is now, not as it was listed. A file made since then is asked about too, never
  replaced without asking.
- Replace keeps the old file until the new copy is complete.
- Some copies can't rename (archives, copies between two servers): then only **Replace** and **Skip** are offered.
- On Windows and Mac servers, names that differ only in case count as the same name.


---

Source: https://kleash.github.io/airscp/files/copy-between-servers.html

# Copy between two servers

The left pane can show another connected server instead of this Mac. Then you copy straight from one server to the
other.

## Steps

1. Connect both servers.
2. Select the server you want on the right in the sidebar.
3. In the left pane, open the pop-up menu at the top (it says **This Mac**) and choose the other server.
4. Drag files between the panes, or use the **Copy** button under a pane.

(Picture: The left pane shows the server backup, the right pane web-01)

## Tips

- The copy streams through your Mac: the two servers don't need to reach each other.
- Choose **This Mac** in the pop-up menu to go back.
- If the other server's connection drops, its copy runs again once it has reconnected.


---

Source: https://kleash.github.io/airscp/files/edit-files.html

# Open and edit a server file

Open a server file in its Mac app, preview it, or edit a text file right in AirSCP.

## Steps

- **Edit a text file in AirSCP**: select it and choose **File ▸ Edit in AirSCP** (or right-click it). Change the text
  and press <kbd>⌘S</kbd> to save it back to the server.
- **Open in its app**: double-click the file, or choose **File ▸ Open** (<kbd>⌘O</kbd>). AirSCP downloads it and opens
  it. When you save it in that app, AirSCP offers to upload it again.
- **Preview**: press <kbd>Space</kbd> (Quick Look), for files up to 100 MB.

(Picture: AirSCP's editor with notes.txt from the server, and Revert and Save buttons)

## Tips

- AirSCP's editor opens plain text files (UTF-8) up to 4 MB.
- Saving is safe: the new text is written next to the file and then renamed over it, so a full disk can't leave it half
  written. The file keeps its permissions.
- Closing an editor with unsaved changes asks first.
- **Find** (<kbd>⌘F</kbd>) opens the find bar; click its **Replace** box to replace text too. **Go to Line…**
  (<kbd>⌘L</kbd>) jumps to a line by its number.
- **Revert to Server Version** reads the file from the server again (asking first when you have unsaved changes).
- If someone saved the file on the server after you opened it, **Save** asks first. **Overwrite** replaces their
  changes with your text. **Show Server Version** opens their text in another window, so you can copy what you need;
  then save again. **Cancel** lets you keep editing.

## If something goes wrong

- **“The file isn't plain text (UTF-8), so AirSCP's editor can't open it”**: use **Open** to open it in its app.
- **“The file is over 4 MB, too large for AirSCP's editor”**: use **Open** instead.


---

Source: https://kleash.github.io/airscp/files/manage-files.html

# New folder, rename, duplicate, delete, Get Info

Everyday file commands work on servers like in Finder. Right-click a file, or use the **File** menu.

## Steps

- **New folder**: **File ▸ New Folder…** (<kbd>⇧⌘N</kbd>). Type a name, click **Create**.
- **New empty file**: **File ▸ New File…**.
- **Rename**: select one item, **File ▸ Rename…**.
- **Duplicate**: **File ▸ Duplicate** (<kbd>⌘D</kbd>) makes “name 2” next to it.
- **Delete**: **File ▸ Delete…** (<kbd>⌘⌫</kbd>). On a server AirSCP asks first, and names the host. On this Mac, items
  go to the Trash.
- **Get Info**: **File ▸ Get Info** (<kbd>⌘I</kbd>) shows the kind, path, size, dates, owner and group, and lets you
  change the permissions.
- **Checksum**: in Get Info, choose **SHA-256** (or SHA-1, MD5) and click **Calculate**. Paste a published checksum
  into the field below to see **✓ Matches** or **✗ Doesn't match**. On a file-transfer-only account AirSCP downloads
  a temporary copy to work it out.
- **Copy the path**: **File ▸ Copy Path** (<kbd>⌥⌘C</kbd>).

(Picture: The New folder sheet with the name drafts)

(Picture: The question: Delete notes.txt on web-01? This can't be undone)

(Picture: Get Info for deploy.sh: kind, path, size, dates, owner and permissions)

## Tips

- Delete on a server can't be undone. Turn the question off only if you are sure: **Settings ▸ Ask before deleting on
  a server**.
- Deleting folders works on file-transfer-only (sftp) accounts too.
- A folder that is too big to read whole in Get Info says so.


---

Source: https://kleash.github.io/airscp/files/permissions.html

# Change permissions

Permissions say who may read, change and run a file on a server (`chmod`).

## Steps

1. Select the items and choose **File ▸ Permissions…**.
2. Tick the boxes: **Read**, **Write** and **Execute**, for the **Owner**, the **Group** and **Others**.
   Or type the number in **Octal (chmod)**, for example `755` or `644`.
3. To change who owns them, type a user in **Owner** or a group in **Group** (a name, or a number). Leave them as they
   are to keep them. On a file-transfer-only account, type numbers (user and group IDs).
4. For folders: tick **Change everything in the folders too** to change what is inside as well.
5. Click **Apply**.

(Picture: The Permissions sheet with Read, Write and Execute boxes and the octal number 755)

## Tips

- **Read** lets someone see the file, **Write** change it, **Execute** run it (or enter a folder).
- **File ▸ Make Executable** is a shortcut for `chmod +x`: a script can then run.
- When you change a whole folder, folders keep their Execute box where they can be read, so a mode like `640` doesn't
  lock you out of them.
- A symbolic link has its target's permissions: change those on the target.
- Only root can give a file to another user; you can change the group to one you belong to.


---

Source: https://kleash.github.io/airscp/files/compress-and-extract.html

# Compress and extract on the server

Make a `.zip` or `.tar.gz` archive on the server, or unpack one there. Nothing goes through your Mac.

## Steps

**Compress**

1. Select the items and choose **File ▸ Compress…**.
2. Choose **ZIP archive (.zip)** or **Gzipped tar archive (.tar.gz)**.
3. Click **Compress**. The archive appears next to the items.

**Extract**

- **File ▸ Extract Here** unpacks the selected archive in its folder. AirSCP asks before it replaces items.
- **File ▸ Extract to New Folder** unpacks it into a new folder named after the archive.

(Picture: The Compress sheet with the archive type)

## Tips

- A format the server can't make is greyed out, and the sheet says why (for example: no `zip` on the server).
- To get an archive onto your Mac without using space on the server, see
  [Download as one archive](https://kleash.github.io/airscp/transfers/download-as-archive.html).


---

Source: https://kleash.github.io/airscp/files/select-and-compare.html

# Select by pattern, compare folders, move, link

Commands for many files at once, and for arranging files on a server.

## Select

- **Edit ▸ Select by Pattern…** (<kbd>⌘+</kbd>): type names or patterns, separated by commas, for example `*.log` or
  `report-??.pdf`. Case doesn't matter. The matching items are added to the selection.
- **Edit ▸ Deselect by Pattern…** (<kbd>⌘-</kbd>): takes the matching items out of the selection.
- **Edit ▸ Select Same Kind**: selects every item with the selected item's extension (all `.jpg` files, say).
- **Edit ▸ Invert Selection** (<kbd>⇧⌘I</kbd>): selects what wasn't selected.
- **File ▸ Copy Names**: copies the names of the selection, one per line (**Copy Path** copies full paths).

## Compare two folders

1. Show a folder on this Mac in one pane and a server's folder in the other.
2. Choose **File ▸ Compare Folders**.
3. The names that differ turn blue in both panes. Point at one to see why: **Only here**, **Newer here**, **Older
   here** or **Another size**.

Compare Folders looks at the two folders only, not inside their subfolders. The marks go when the pane lists again.
To make the folders the same, use [Synchronize](https://kleash.github.io/airscp/synchronize.html).

## Move or copy within a server

- **File ▸ Move To…**: type a folder on the same server (its full path, `~/…` in your home folder, or one relative to
  the folder shown). The other pane's folder is filled in when it shows the same server.
- **File ▸ Copy To…**: the same, as a copy. It needs an account that runs commands (not file transfer only).
- When a name is taken there, AirSCP asks [Replace, Keep Both or Skip](https://kleash.github.io/airscp/files/replace-or-keep-both.html).

## Make a symbolic link

1. Select the file or folder to link to (or nothing).
2. Choose **File ▸ New Symbolic Link…**, type the link's name, click **Next**.
3. Type what it points to, click **Create**. A relative path (like `../shared/config.yml`) keeps working when the
   folder moves.

## Go to the other pane's folder

**Go ▸ Other Pane's Folder** (<kbd>⌥⌘O</kbd>) shows the folder the other pane shows, when both panes show this Mac or
the same server.

## Tips

- Windows servers can't make symbolic links over SSH: the command is greyed out there.


---

Source: https://kleash.github.io/airscp/transfers/

# Transfers and the queue

Every upload and download goes into the **Transfers** list at the bottom of the window. Transfers run in the
background, so you keep browsing. Each host runs one transfer at a time; different hosts run at the same time.

(Picture: The Transfers list: one upload running, one paused, one done and verified)

## What the list shows

Each row shows the host, the name, the way (up for uploads, down for downloads), the size, the progress, the status
and the speed. A copy between two servers shows both hosts, “A → B”.

## Steps

- **Cancel** one transfer: select it and click **Cancel**. **Cancel All** stops them all (AirSCP asks first).
- **Pause** a transfer: right-click it and choose **Pause**, later **Resume**. **Pause All** and **Resume All** do it for
  every transfer.
- **Retry** a failed transfer: select it and click **Retry**.
- **Remove** a row: select it and click **Remove**. **Clear Finished** removes all finished rows.
- **Check a copy**: right-click a finished transfer and choose **Verify with Checksum**.
- **See what went wrong**: right-click a row and choose **Show Details…**.
- **Find a download**: right-click it and choose **Show in Finder**.
- **Change the order**: right-click a queued transfer and choose **Move Up** or **Move Down**: it runs before or after the
  next one waiting for the same host.
- **When Done**: in the list's header, choose what happens once every transfer has finished: **Do Nothing**,
  **Disconnect** (every host), **Sleep This Mac** or **Notify** (a notification, for transfers that took more than 30
  seconds). It happens once, then goes back to Do Nothing.

## Move instead of copy

- Select items and choose **File ▸ Upload and Delete…** (in the This Mac pane) or **File ▸ Download and Delete…** (in a
  server pane), or hold <kbd>⌘</kbd> while you drag between this Mac and a server, as Finder moves between disks.
- AirSCP asks once. Each item is deleted where it was only after its copy is done (and checked, when **Settings ▸ Verify
  transfers with SHA-256** is on): a copy that fails, has errors or doesn't match leaves the original alone. On this
  Mac originals go to the Trash.
- Folders with **Leave out** patterns stay where they are, since some of what is in them wasn't copied.

## Pages

- [When the connection drops during a transfer](https://kleash.github.io/airscp/transfers/resume.html)
- [Limit the speed](https://kleash.github.io/airscp/transfers/speed-limit.html)
- [Download as one archive](https://kleash.github.io/airscp/transfers/download-as-archive.html)
- [Pause and resume transfers](https://kleash.github.io/airscp/transfers/pause-and-resume.html)
- [Check a copy with its checksum](https://kleash.github.io/airscp/transfers/verify-checksums.html)

## Tips

- The Dock icon shows how many transfers are waiting or running.
- While transfers run, your Mac doesn't go to sleep and doesn't slow AirSCP down.
- Quitting AirSCP while transfers run asks first.
- Hide or show the list: **View ▸ Hide Transfers**.


---

Source: https://kleash.github.io/airscp/transfers/resume.html

# When the connection drops during a transfer

If the connection is lost in the middle of a transfer, AirSCP keeps what was copied. After reconnecting, a single file
continues where it stopped instead of starting again.

## Steps

1. Wait: AirSCP reconnects by itself (see [Stay connected](https://kleash.github.io/airscp/connecting/stay-connected.html)) and runs the transfers
   again.
2. Or select the failed transfer and click **Retry**.

(Picture: The Transfers list with Retry and Clear Finished buttons)

## Tips

- Single files continue where they stopped. Folders and archive streams start again.
- While AirSCP reconnects to the server by itself, **Retry** waits: the cut-off transfers run again on their own once
  the connection is back.
- If the kept part is gone, or the file on the other side got shorter, the file is copied again from the start.
- AirSCP can't tell whether the source file changed between the tries. Retry only a file that stayed the same.
- **Remove**, **Clear Finished**, **Cancel All**, disconnecting and quitting throw the kept part away.


---

Source: https://kleash.github.io/airscp/transfers/speed-limit.html

# Limit the speed

Big transfers can fill a slow or shared connection. A speed limit leaves room for everything else.

## Steps

1. In the Transfers list, click **Speed** (it shows the limit now, for example **Speed: Unlimited**).
2. Choose **1 MB/s**, **5 MB/s**, **10 MB/s** or **50 MB/s**. **Unlimited** is the default.

(Picture: The Speed menu set to 5 MB/s above the Transfers list)

## Tips

- The limit applies to every host's transfers that start from then on. Transfers that are running keep their speed.
- Large files copy at scp's full speed when there is no limit.


---

Source: https://kleash.github.io/airscp/transfers/download-as-archive.html

# Download as one archive

Download files and folders as one `.tar.gz` archive. The server packs it while it sends it, so it needs no free space on
the server.

## Steps

1. Select the items in the server pane.
2. Choose **File ▸ Download as .tar.gz…** (or right-click them).
3. Optional: tick **Unpack it after the download (the archive is removed)** to get the items instead of the archive.
4. Click **Download**.

(Picture: The question: Download logs as a .tar.gz archive? with the Unpack option)

## Tips

- The archive goes into the folder the left pane shows. When the left pane shows a server, it goes into your downloads
  folder (**Settings ▸ Downloads folder**).
- The progress shows the bytes received, not a percentage: the size is known only at the end.
- The other way round: **File ▸ Upload Compressed** packs Mac items into one stream and unpacks them on the server.


---

Source: https://kleash.github.io/airscp/transfers/pause-and-resume.html

# Pause and resume transfers

Pause a transfer to free the connection for something else, and resume it later. A single file continues where it
stopped.

## Steps

1. In the Transfers list, right-click a transfer and choose **Pause**. Select several transfers to pause them together.
2. To go on, right-click it and choose **Resume**.

To pause or resume every transfer at once, click **Pause All** or **Resume All** above the list.

(Picture: The Transfers list: one upload running, one paused, one verified)

## Tips

- A paused transfer waits until you resume it, even when the connection drops and comes back.
- Single files continue where they stopped. Folders, archives and copies between two servers start again.
- While AirSCP reconnects to the server by itself, **Resume** waits: resume once the connection is back.
- AirSCP can't tell whether a file changed while its transfer was paused. Resume only a file that stayed the same, or
  turn on **Verify transfers with SHA-256** in Settings to check the copy.
- **Cancel** a paused transfer to throw away the part that was copied. Disconnecting and quitting do that too, and
  AirSCP asks first.
- Paused transfers don't keep your Mac awake, and the Dock icon doesn't count them.


---

Source: https://kleash.github.io/airscp/transfers/verify-checksums.html

# Check a copy with its checksum

AirSCP can make sure that a copied file is exactly the same as the original. It compares their SHA-256 checksums: a
fingerprint of every byte in the file.

## Steps

- **One transfer**: right-click a finished transfer in the Transfers list and choose **Verify with Checksum**.
- **Every transfer**: turn on **AirSCP ▸ Settings ▸ Verify transfers with SHA-256**. Each file is checked as soon as it
  arrives.

The status then says:

- **Verified**: the copy and the original are the same.
- **Mismatch** (red): they differ. The copy was damaged, or one of them changed after the copy was made. Click
  **Retry** to copy the file again. AirSCP replaces the bad copy and checks the new one.
- **Not verified**: AirSCP couldn't check it. Point at the status to see why.

(Picture: The Transfers list with a verified upload)

## Tips

- Only single files are checked, not folders or archives.
- The server works out its checksum with `sha256sum` or `shasum`. Accounts that allow file transfers (sftp) only can't
  run them, so their copies show **Not verified**.
- Checking reads the whole file on both sides, so big files take longer.
- To see the checksum, point at **Verified** in the list.


---

Source: https://kleash.github.io/airscp/synchronize.html

# Synchronize two folders

Make a folder on your Mac and a folder on a server the same. AirSCP compares them, with everything inside, and shows
what it would copy. Nothing is copied until you click **Synchronize**.

## Steps

1. Connect to the server. Show the Mac folder in the left pane and the server folder in the right pane.
2. Choose **File ▸ Synchronize…** (or right-click the folder).
3. Choose the direction:
   - **This Mac → server**: upload what is new or newer on the Mac.
   - **server → This Mac**: download what is new or newer on the server.
   - **Both ways**: copy the newer file each way, and what is missing on either side.
4. Optional, one way only: tick **Delete what is only on …** to also delete what the other side doesn't have. On a
   server it is deleted; on your Mac it goes to the Trash.
5. Optional: in **Leave out**, type names or patterns to skip, separated by commas, for example
   `*.log, node_modules, .git`. AirSCP doesn't compare, copy or delete what matches, in any folder. It is the same list
   as for folder uploads and downloads to this server, and AirSCP remembers it. AirSCP compares again as you type.
6. Check the list. Untick an item to leave it as it is, or use **Select All** and **Select None**. The line under the
   list counts the ticked items and adds up their sizes.
7. Click **Synchronize**. The copies run in the Transfers list.

(Picture: The Synchronize Folders sheet: Leave out, and five ticked uploads from this Mac to web-01)

## How AirSCP compares

- Two files count as the same when their sizes and their modification times match. Times count to the minute, because
  that is what servers list. For files older than six months, servers list only the day. A server file dated after
  the server's own clock also shows only its day: it counts as the newer file.
- The copies keep their modification times, so a second compare finds nothing to do.
- Some items are left as they are, and the sheet says how many. These are: files that are newer on the side being
  updated, a file on one side against a folder on the other, symbolic links, `.DS_Store` files, and AirSCP's own
  temporary `.airscp-*` items.
- What matches **Leave out** is not compared. A folder that matches is not even read, so comparing is faster.
- A folder that is only on one side is copied as one piece, without what matches **Leave out** inside it. A server
  without `tar` (such as an sftp-only account) gets the whole folder. **Delete…** deletes such a folder with
  everything in it.

## Options

- **Compare by**: **Size and date** (the default), **Size only**, **Date only**, or **Contents (SHA-256)**. Contents
  works out a checksum of each pair of files of the same size, on this Mac and on the server: slower, but exact, for
  servers whose clocks or copies don't keep times. It needs an account that runs commands.
- **Only files on both sides**: leave alone what is only on one side; only files both sides have are updated.
- **Also replace newer files on …** (one way only): the destination becomes a copy of the source, newer files too.
- **Reverse**: right-click a file in the list to copy it the other way: the other side's copy replaces this side's.

## Tips

- When one of the folders is a home folder or `/`, AirSCP waits for you to click **Compare**: comparing everything can
  take minutes.
- 20 or more files of one folder go as one stream, which is faster.
- The **?** button in the sheet opens this page.

## If something goes wrong

- **“Can't list … Nothing was copied or deleted.”**: a folder couldn't be read (often permissions). Add its name to
  **Leave out**, or fix it and compare again.
- Two versions with the same size saved within the same minute count as the same: the server lists times to the
  minute.


---

Source: https://kleash.github.io/airscp/disk-usage.html

# See what takes the room on a disk

Find the big folders and files below a folder, on a server or on this Mac, and delete what you don't need.

## Steps

1. In a pane, open the folder to look into (or select one folder in it).
2. Choose **File ▸ Disk Usage…**, or right-click an empty part of the pane.
3. AirSCP scans everything below the folder. While it runs, the bar shows how far it is, the files it finds show
   with their sizes, and the rings and the list grow as the sizes add up.
4. The rings: the folder is in the middle, its items around it, and what is in them further out. The wider an arc,
   the more room it takes. Point at an arc to see its name and size. Click a folder's arc to go into it; click the
   middle to go up.
5. The list: the folder's items, largest first, with their share of the folder. Double-click a folder to go into it,
   or click **↑** to go up. Choose **Largest Files** to see the 200 biggest files at any depth below.
6. Select what you don't need and click **Delete…**. AirSCP asks first. On a server it deletes the items (folders with
   everything in them); on this Mac it moves them to the Trash: empty the Trash to free the space.
7. Or select an item and click **Show** (or right-click ▸ **Show in Pane**): the pane goes to its folder and selects
   it. **Copy Paths** copies the full paths, one per line. On this Mac, **Show in Finder** selects them in a Finder
   window.

## Tips

- **Stop** ends a long scan; the sizes then count what it scanned so far. **Scan Again** measures everything again.
- The scan stays on the folder's own disk: other disks mounted inside it are left out.
- Sizes are the files' own sizes, as the panes show them.
- On a server, AirSCP runs one `du` command. It needs a server with a shell (not file-transfer-only accounts).
- To see the size of each folder in the pane itself, use **View ▸ Calculate Folder Sizes**.

## If something goes wrong

- **Delete… is greyed out**: wait for the scan to end, or click **Stop**.
- **A folder you can't read** counts as empty: open it as root (see [Browse as root](https://kleash.github.io/airscp/connecting/browse-as-root.html))
  and scan again.
- Disk Usage doesn't work on S3 storage.


---

Source: https://kleash.github.io/airscp/find.html

# Find files on a server

Search for files by name in a server folder and in every folder below it.

## Steps

1. In the server pane, open the folder to search in.
2. Choose **File ▸ Find Files…** (<kbd>⇧⌘F</kbd>), or right-click the folder.
3. Type a name, or part of one. Or a pattern, for example `*.log`. `*`, `?` and `[ ]` work; case doesn't matter.
4. Click **Find**.
5. Select a result and click **Show** (or double-click it): the pane goes to its folder and selects it.
6. Or select several results (<kbd>⌘</kbd>-click, <kbd>⇧</kbd>-click) and click **Download…** (to a folder on
   this Mac), **Delete…** (on the server, after asking) or **Copy Paths**. Right-click a result for the same.

(Picture: Find Files in dev with *.log: three results)

## Tips

- Text without `*` or `?` finds names that contain it: `report` finds `report.pdf` and `old-report.txt`.
- Up to 10,000 results. They show as they are found. **Stop** ends a long search and keeps what it found; **Done**
  closes the sheet.
- On servers with a shell, AirSCP runs one `find` command. On file-transfer-only (sftp) accounts it lists folder after
  folder, which is slower.
- To narrow the files the pane shows instead, use **Filter by name** at the top of the pane (<kbd>⌘F</kbd>).

## If something goes wrong

- **“Nothing found below …”**: try part of the name, or a pattern like `*.log`.
- Find Files searches servers. For files on your Mac, use Spotlight or Finder.


---

Source: https://kleash.github.io/airscp/remote-desktop/

# Remote Desktop (Windows)

AirSCP has a built-in Remote Desktop client. It opens a Windows computer's desktop right in AirSCP's window, with the
clipboard and file copying both ways. Nothing else needs to be installed.

(Picture: A Windows desktop in AirSCP's window, with the bar: Ctrl+Alt+Del, Full Screen, Send Files, Shared Folder and Disconnect)

## Pages

- [Add a Windows computer](https://kleash.github.io/airscp/remote-desktop/add-a-windows-computer.html)
- [Connect and log in](https://kleash.github.io/airscp/remote-desktop/connect.html)
- [Copy files to and from Windows](https://kleash.github.io/airscp/remote-desktop/copy-files.html)
- [Copy and paste between Mac and Windows](https://kleash.github.io/airscp/remote-desktop/clipboard.html)
- [Keyboard, mouse and screen size](https://kleash.github.io/airscp/remote-desktop/keyboard-and-screen.html)
- [Self-signed certificates and corporate networks](https://kleash.github.io/airscp/connecting/self-signed-certificates.html)

## Tips

- Windows must allow Remote Desktop: on the Windows computer, **Settings ▸ System ▸ Remote Desktop**. Windows Home
  editions don't have it.
- A Windows computer behind a server? Set **Connect through** to that SSH host.


---

Source: https://kleash.github.io/airscp/remote-desktop/add-a-windows-computer.html

# Add a Windows computer

Save a Windows computer once. Then double-click it in the sidebar to open its desktop.

## Steps

1. Choose **File ▸ New Remote Desktop…** (or click **+** in the toolbar).
2. Type its **Address**. Only the address is required.
3. Optional: **User name** and **Password**. Leave them empty to be asked when you connect.
4. Optional: **Connect through** an SSH host, for a Windows computer you can only reach through a server.
5. Click **Add**.

(Picture: The Remote Desktop sheet: name, address, Connect through, clipboard and shared folder)

| Setting | What it does |
|---|---|
| **Share the clipboard (text and files)** | Copy on one side, paste on the other. On by default. |
| **Share a Mac folder with Windows** | Windows sees the folder as `\\tsclient\AirSCP`. Files you drop on the desktop land there; files copied into it in Windows come back to the Mac. |
| **Folder** | The shared Mac folder. Empty: `~/Downloads/AirSCP RDP`. |

## Advanced

(Picture: Advanced: port, domain, display, Retina resolution, ⌘ as Ctrl and server certificate)

| Setting | What it does |
|---|---|
| **Port** | Empty: 3389, Remote Desktop's usual port. |
| **Domain** | For a company (domain) account. You can also type `DOMAIN\user` as the user name. |
| **Display** | **Fit the window** (the desktop follows the window's size), a fixed size, or **Full screen**. |
| **Retina resolution (sharp text)** | On a Retina screen, Windows gets the full resolution and scales to 200 %. |
| **⌘ acts as Ctrl** | On by default: ⌘C copies in Windows. Off: ⌘ is the Windows key. |
| **Server certificate** | How AirSCP checks the computer's certificate. See [Self-signed certificates and corporate networks](https://kleash.github.io/airscp/connecting/self-signed-certificates.html). |

## Tips

- **Test Connection** checks that Windows answers and accepts the user name and password, without starting a session.
  With **Connect through** set, it connects that SSH host first; its questions (a password, a new server key) appear
  on the sheet.
- The **?** button in the sheet opens this page.


---

Source: https://kleash.github.io/airscp/remote-desktop/connect.html

# Connect and log in

## Steps

1. Double-click the computer in the sidebar (or select it and press <kbd>⌘K</kbd>, or click **Connect**).

   (Picture: Office PC selected, not connected yet: Connect to show the Windows desktop here)

2. The first time, AirSCP shows the computer's certificate: who it was issued to, by whom, and its fingerprint.
   Click **Always Trust** to remember it, or **Trust Once** for this time only.
3. If no password is saved, AirSCP asks: type the **User name** and **Password** (and the **Domain** for a company
   account). Tick **Remember the password in Keychain** to save it.
4. Click **Log In**. The Windows desktop appears in AirSCP's window.

(Picture: The Log in to Office PC sheet with user name, domain and password)

To end the session, click **Disconnect** in the bar, or choose **Host ▸ Disconnect** (<kbd>⌘E</kbd>).

## Tips

- Connected desktops stay connected while you look at a server. Switch with <kbd>⌘1</kbd> to <kbd>⌘9</kbd>.
- A password typed with Remember is saved only after Windows has checked it.
- Through an SSH host, AirSCP connects that host first and opens a tunnel through it.

## If something goes wrong

- **“The user name or password is incorrect”**: try again. A company account needs its domain (the Domain field, or
  `DOMAIN\user`).
- **“AirSCP couldn't reach the server”**: check the address, that Remote Desktop is on in Windows, and your VPN.
  macOS may ask once whether AirSCP may find devices on your local network: choose **Allow**.
- **“The certificate of … has changed”**: someone may be in the middle of the connection, or the computer got a new
  certificate. Trust it only if you know why it changed.
- **“The session was disconnected in Windows”**: another login took it over. Reconnect to take it back.


---

Source: https://kleash.github.io/airscp/remote-desktop/copy-files.html

# Copy files to and from Windows

A Mac folder is shared with Windows, where it is `\\tsclient\AirSCP`. Files go both ways through it.

## Open the shared folder in Windows

- The bar says “In Windows, open `\\tsclient\AirSCP`”. Click the copy button next to it. Then paste the path into
  Explorer's address bar in Windows (or into **Run**: <kbd>Win</kbd>+<kbd>R</kbd>) and press Enter.
- Or in Explorer: **This PC ▸ Redirected drives and folders ▸ AirSCP on** *your Mac's name*.

## Steps

**Mac to Windows**

- Drop files from Finder onto the Windows desktop in AirSCP, or click **Send Files…** in the bar. They are copied into
  the shared folder. The bar says where: “In Windows: `\\tsclient\AirSCP\…`”.
- Or copy files in Finder and paste them in Windows Explorer (see [Copy and paste](https://kleash.github.io/airscp/remote-desktop/clipboard.html)).

**Windows to Mac**

- In Windows, copy files into `\\tsclient\AirSCP`. They appear in the Mac folder. **Shared Folder** in the bar shows it
  in Finder.
- Or copy files in Explorer and use **Paste Items to Mac…** in the bar.

(Picture: Explorer in Windows on \\tsclient\AirSCP, and the bar: In Windows: \\tsclient\AirSCP\…)

## Windows shows tsclient, but no AirSCP folder

Some Windows computers don't allow shared folders: a company setting (the Group Policy **Do not allow drive
redirection**) turns them off. Explorer then shows **tsclient** under **Network**, but it is empty, and the bar says
“Windows' policy blocks the shared folder”.

- Copy and paste the files instead (see [Copy and paste](https://kleash.github.io/airscp/remote-desktop/clipboard.html)). The bar says so when Windows allows the
  clipboard.
- Or ask the computer's administrator to allow drive redirection.

## Tips

- The shared folder is `~/Downloads/AirSCP RDP` unless the desktop's settings name another.
- Names Windows can't store get “_” for the characters it refuses.
- Copies from the Mac to Windows run at about 9 MB/s; from Windows to the Mac at about 1–1.5 MB/s. For big files from
  Windows, sftp to Windows' own OpenSSH server is faster.
- Disconnecting while Windows copies into the shared folder asks first.


---

Source: https://kleash.github.io/airscp/remote-desktop/clipboard.html

# Copy and paste between Mac and Windows

Text and files go both ways through the clipboard, like on one computer.

## Steps

- **Text**: copy on the Mac, click the Windows desktop, paste with <kbd>⌘V</kbd>. The other way: copy in Windows
  (<kbd>⌘C</kbd>), switch to a Mac app, paste.
- **Files, Mac to Windows**: copy files in Finder, then paste them in Windows Explorer.
- **Files, Windows to Mac**: copy files in Explorer. Then click **Paste Items to Mac…** in the bar (any size, with
  progress), or switch to Finder and paste with <kbd>⌘V</kbd> (up to 256 MB).

(Picture: The Windows desktop in AirSCP with the bar above it)

## Tips

- Clipboard sharing is on by default. Turn it off in the desktop's settings: **Share the clipboard (text and files)**.
- Text over 1 MB isn't sent to Windows (very large pastes froze Windows sessions in tests). The bar says so.
- Something Windows can't take, such as an image, isn't sent.


---

Source: https://kleash.github.io/airscp/remote-desktop/keyboard-and-screen.html

# Keyboard, mouse and screen size

## Keyboard

- While the Windows desktop has the focus, keys go to Windows. macOS keeps a few, such as <kbd>⌘Tab</kbd>.
- <kbd>⌘</kbd> acts as Ctrl, so <kbd>⌘C</kbd> and <kbd>⌘V</kbd> copy and paste in Windows. Prefer the Windows key? Turn
  off **⌘ acts as Ctrl** in the desktop's **Advanced** settings.
- **Ctrl+Alt+Del** has a button in the bar.
- Click the sidebar to get <kbd>⌘1</kbd> to <kbd>⌘9</kbd> back for switching.

## Screen size

- **Fit the window** (default): the Windows desktop follows the size of AirSCP's window.
- A fixed size, or **Full screen** (below).
- On a Retina screen, Windows gets the full resolution and scales to 200 %, so text is sharp.

## Full screen

- **Full Screen** in the bar, **View ▸ Enter Full Screen** or <kbd>⌃⌘F</kbd> shows the Windows desktop on the whole
  screen. For a few seconds, a note at the top says how to leave.
- To leave, press <kbd>⌃⌘F</kbd>. Or move the pointer to the top of the screen: the menu bar comes down. Choose
  **View ▸ Exit Full Screen**.
- The desktop's **Full screen** setting (under **Advanced**) opens it full screen each time.

(Picture: Advanced settings: display, Retina resolution and ⌘ acts as Ctrl)

## Tips

- <kbd>⌘Q</kbd> still quits AirSCP (it asks first while Windows copies files).
- Audio, printers, smart cards and several monitors aren't supported.


---

Source: https://kleash.github.io/airscp/s3/

# S3 storage

AirSCP opens Amazon S3 and storage that works like it (MinIO, Cloudflare R2, Backblaze B2, Wasabi, Ceph and others).
Its buckets open in the Files tab like a server's folders: you browse, drag files in and out, rename, delete, edit and
zip, and long copies wait in the Transfers list.

## Pages

- [Connect to S3 or S3-compatible storage](https://kleash.github.io/airscp/s3/connect.html)
- [Browse and transfer](https://kleash.github.io/airscp/s3/browse-and-transfer.html)
- [Zip and extract](https://kleash.github.io/airscp/s3/zip-and-extract.html)

## Good to know

- A bucket is a folder at the top. Folders inside a bucket are parts of the file names (`photos/2024/a.jpg`): an
  empty folder is kept as an empty object named `folder/`.
- S3 storage keeps files only. It has no commands, terminal, tunnels, permissions or symbolic links: those menu
  items are off, and their tooltip says why.
- AirSCP doesn't make or delete buckets. Do that in your provider's console.


---

Source: https://kleash.github.io/airscp/s3/connect.html

# Connect to S3 or S3-compatible storage

Save your storage once, with its access key. Then double-click it in the sidebar to see its buckets.

## Steps

1. Choose **File ▸ New S3 Connection…**, or click **+** in the toolbar and choose **New S3 Connection…**.
2. Fill in the fields (see the table below).
3. Click **Test Connection** to check the keys without saving (optional).
4. Click **Add**. The connection appears in the sidebar under **S3 Storage**.
5. Double-click it. Its buckets appear in the right pane.

(Picture: New S3 Connection with a name, an endpoint and an access key, after Test Connection: Connected: 2 buckets)

| Field | What to type |
|---|---|
| **Name** | A short name for the sidebar, for example `Photos`. Optional. |
| **Endpoint** | Leave it empty for Amazon S3. For other storage, the address your provider gives, for example `https://<account>.r2.cloudflarestorage.com` or `http://192.168.1.10:9000`. A plain `http://` address works only with an IP address or a local name (`nas`, `nas.local`): macOS wants `https://` for other names. |
| **Region** | Optional for Amazon S3: AirSCP finds each bucket's region by itself. For other storage, the region they name (Cloudflare R2: `auto`). |
| **Access key ID** | The key's ID from your provider's console. |
| **Secret access key** | The key's secret. It goes to your Keychain, never to AirSCP's settings file. |
| **Bucket** | Optional. The bucket to open first. Needed when your key may not list the buckets. |
| **Group** | A group to sort the connection under in the sidebar. |

## Advanced

| Setting | What it does |
|---|---|
| **Path-style addresses** | Puts the bucket in the address's path (`https://host/bucket`) instead of the host name. Most self-hosted storage (MinIO, Ceph) wants it. An endpoint at an IP address always uses it. |
| **Session token** | Only for temporary keys. It goes to your Keychain. |
| **Proxy** | Only when your network reaches the internet through a proxy. See [Connect through a proxy](https://kleash.github.io/airscp/connecting/proxies.html). |

## Import from ~/.aws

Do you use the AWS command line tool? Choose **File ▸ Import from ~/.aws…**. AirSCP makes a connection for each
profile that has its own access key, with its region and `endpoint_url`. The secret keys go to your Keychain; the
files in `~/.aws` stay as they are. The App Store version asks you to allow your `.aws` folder the first time.

Profiles that sign in with single sign-on (SSO), get their keys from a program (`credential_process`) or take on a
role (`role_arn`) can't be imported. AirSCP lists them with the reason. Make an access key for such an account, and
add it with **New S3 Connection…**.

## Change, copy or delete a connection

- **Host ▸ Edit…** changes the selected connection.
- **Host ▸ Duplicate** makes a copy, with its keys.
- **Host ▸ Delete…** forgets the connection and its keys. The files on the storage stay.
- **Host ▸ Copy Link** copies the `s3://bucket/folder/` link of the folder you see.

## Tips

- "The secret key doesn't match the access key": edit the connection and type the secret key again.
- "This Mac's clock is too far off": turn on **Set time and date automatically** in System Settings ▸ General ▸
  Date & Time. S3 refuses requests from a clock that is wrong by more than 15 minutes.
- "This access key may not list the buckets": type the bucket's name in **Bucket**.
- The **?** button in the sheet opens this page.


---

Source: https://kleash.github.io/airscp/s3/browse-and-transfer.html

# Browse and transfer

S3 storage works in the Files tab as a server does. This Mac is on the left, the storage on the right.

(Picture: The bucket example-shop-media on the right, with its folders and files; a website folder of this Mac on the left)

## Steps

- **Open a bucket or folder**: double-click it.
- **Upload**: drag files or folders from the left pane or from Finder onto the right pane. Or select them on the left
  and click **Upload**.
- **Download**: drag items to the left pane or to Finder. Or select them and click **Download**, or choose
  **File ▸ Download To…**.
- **New folder**: **File ▸ New Folder…**. **New file**: **File ▸ New File…**.
- **Rename, move, copy**: **File ▸ Rename…**, **File ▸ Move To…**, **File ▸ Copy To…**. A folder moves with
  everything in it.
- **Delete**: select items and press <kbd>⌫</kbd>. AirSCP asks first. A folder goes with everything in it.
- **Edit a text file**: **File ▸ Edit in AirSCP**. When you save, AirSCP checks that nobody changed the file meanwhile.
- **Get Info**: size, date, content type, storage class, ETag, the SHA-256 checksum the storage keeps, and the file's
  metadata.
- **Find Files…**: search names below the folder you see.
- **Synchronize…**: make a Mac folder and a storage folder the same, by size and date. See [Synchronize](https://kleash.github.io/airscp/synchronize.html).

## Copy a link

Right-click a file:

- **Copy S3 Link** copies its `s3://bucket/key` address, for tools such as the AWS command line.
- **Copy Presigned Link…** makes an `https` link that anyone can open without keys. Choose how long it works: an hour,
  a day, or 7 days (the longest S3 allows).

## Copy between a server and S3

Choose a connected server in the left pane's menu (where it says **This Mac**). Then drag items between the server and
the storage. They go through your Mac.

## Transfers

Every upload and download waits in the Transfers list. You can pause and resume it, cancel it, retry it and limit its
speed, as for a server. See [Pause and resume](https://kleash.github.io/airscp/transfers/pause-and-resume.html) and [Verify with checksums](https://kleash.github.io/airscp/transfers/verify-checksums.html).

- Big files (from 64 MB) go in parts. A paused upload keeps the parts that arrived, and **Resume** sends only the rest.
- A paused download keeps what arrived, and **Resume** continues from there.
- **Verify** compares the file's SHA-256 checksum on your Mac with the one the storage keeps. Storage that keeps no
  checksum for a file says so.
- A file appears on the storage only when it has arrived whole.
- In a folder you upload, a symbolic link to a file goes as that file. A link to a folder is left out, and the
  transfer names it.

## Tips

- S3 has no real folders: a folder is the part of the names before a `/`. A name AirSCP can't show as a file (an empty
  name, `.` or `..`) is left out of the list.
- A bucket in another Amazon S3 region works too: AirSCP finds its region.


---

Source: https://kleash.github.io/airscp/s3/zip-and-extract.html

# Zip and extract

S3 storage can't make or open archives itself. AirSCP does it on your Mac, as a job in the Transfers list: it
downloads, zips or unpacks, and uploads.

## Steps

**Download as a .zip**

1. Select the items and choose **File ▸ Download as .zip…**.
2. Click **Download**. The `.zip` lands in the folder the left pane shows (or in your Downloads folder).

**Compress in the bucket**

1. Select the items and choose **File ▸ Compress…**.
2. Click **Compress**. A `.zip` appears next to the items (`Archive.zip` for several items).

**Extract**

- Select a `.zip`, `.tar`, `.tar.gz`, `.tgz` or `.gz` file.
- **File ▸ Extract Here** puts its items in the same folder. When an item of the same name is there already, AirSCP
  puts them in a new folder named after the archive instead: nothing is replaced.
- **File ▸ Extract to New Folder** always puts them in a new folder.

## Tips

- Zips are made with macOS's `ditto`, without Mac-only extras, so they open on Windows and Linux too.
- The job needs room on your Mac for the items while it works. It cleans up when it ends.
- Like any transfer, the job can be paused (it starts again on Resume), cancelled or retried.


---

Source: https://kleash.github.io/airscp/monitor.html

# Watch a Linux server

The **Monitor** tab shows what a Linux server is doing: CPU, memory, disks, processes and the ports it listens on. You can
also stop a process.

## Steps

1. Connect to the server.
2. Click the **Monitor** tab.
3. Read the figures. They refresh every 3 seconds while the tab is on screen.

The top of the window shows the server's CPU, memory and main disk on every tab, refreshed every 10 seconds. It isn't
there for servers that aren't Linux.

(Picture: The Monitor tab: CPU, memory, swap, load, uptime, disks and the list of processes)

| Part | What it shows |
|---|---|
| **CPU** | How busy the processors are, since the last refresh. |
| **Memory** and **Swap** | Used and total. |
| **Load** | The load averages for 1, 5 and 15 minutes. |
| **Up** | How long the server has run since it started. |
| **System** | The server's operating system. |
| **Disks** | Free space on each file system, with a bar. |
| **Processes** | Every process with its PID, user, CPU, memory, time, state and command. |

## Stop a process

1. Type its name, user, command or PID in the search field above the list.
2. Select it and click **Kill** (asks the process to quit) or **Force Kill** (stops it at once).
3. AirSCP asks first. Click **Kill** again to confirm.

(Picture: The question: Kill python3? The process is asked to quit)

## See which ports a server listens on

1. In the **Monitor** tab, click **Ports** above the list of processes.
2. Read the list: each port the server listens on, with the program that listens and how many connections it has.
3. Click a port to see who is connected to it, and how many connections come from each address.

(Picture: Ports: the ports web-01 listens on, and the connections to its website on port 8080)

| Part | What it shows |
|---|---|
| **Protocol** | TCP or UDP. |
| **Address** | Where the port can be reached. 0.0.0.0 and :: mean every address of the server (open to the network); 127.0.0.1 and ::1 mean only the server itself. |
| **PID** and **Process** | The program that listens (+1: one more process shares the port). A dash means another user's program: connect as root to see it. |
| **User** | The account the port belongs to. |
| **Connections** | How many connections are open to it. UDP has no connections. |

To stop the program that has a port, select the port and click **Kill** or **Force Kill**. **Show Process** shows the
program in the list of processes.

## Tips

- Click a column heading to sort the processes, for example by CPU.
- Kill uses your account's rights. When your account may not stop a process, AirSCP offers **Kill with sudo in
  Terminal**, where sudo can ask for your password (on servers that have sudo).
- The list of processes isn't read while the tab isn't shown. The figures at the top of the window still refresh
  every 10 seconds.
- Reading the ports takes some work on the server, so AirSCP reads them only while **Ports** is shown: at once, then
  every 5 seconds. Click **Pause** to keep the list as it is, and **Refresh** to read it again now.
- Type a port, program or address in the search field above the ports to see only those.
- Right-click a port, or a connection, to copy its address.

## If something goes wrong

- **“The system monitor works only on Linux servers”**: macOS and BSD servers aren't supported. The Files and Tunnels
  tabs work as usual.
- **“This account allows file transfers (sftp) only”**: AirSCP can't read the system there. The Files tab works.
- On BusyBox systems (Alpine), processes show no CPU figure.


---

Source: https://kleash.github.io/airscp/tunnels.html

# Open a tunnel (port forwarding)

A tunnel opens a port on your Mac that leads through the server: to the server itself, or to another machine only the
server can reach, such as a database or an internal web page. Or the other way round. It goes through the host's
connection, so nothing else needs to be open.

## Steps

1. Connect to the server and click the **Tunnels** tab.
2. Click **Add Tunnel…**.
3. Choose the type:
   - **Local**: open a port on this Mac. Connections to it go through the server, to the server itself or to another
     machine the server can reach (ssh `-L`).
   - **Remote**: open a port on the server. Connections to it come back through the tunnel, to this Mac or to another
     machine your Mac can reach (ssh `-R`).
   - **SOCKS proxy**: use a port on this Mac as a proxy for your apps. Their traffic leaves from the server (ssh `-D`).
4. Fill in the sentence: the port to open, where it leads (**The server itself**, or **Another machine the server can
   reach** and its name), and the port there. The second port is the same as the first until you change it.
5. Check the line under it. It shows the whole route, for example
   `localhost:8080 on this Mac → web-01 → localhost:80 on web-01 (the server itself)`.
6. Click **Save**, then switch the tunnel on in the list.

(Picture: The tunnel sheet: open port 8080 on this Mac, through web-01, to the server itself, port 80, with the route under it)

(Picture: The Tunnels tab with three saved tunnels, each with its route and its switch)

## Examples

| You want | Type | Open port | To | Port there |
|---|---|---|---|---|
| The server's own web admin page | Local | `8080` on this Mac | The server itself | `80` |
| A database the server can reach | Local | `15432` on this Mac | Another machine: `db-01.internal` | `5432` |
| Let the server reach a dev server on your Mac | Remote | `3000` on the server | This Mac | `3000` |
| Browse as if you were in the server's network | SOCKS proxy | `1080` on this Mac | | |

With the first example on, open `http://localhost:8080` in your browser.

## Tips

- **The server itself** is `localhost` as the server sees it. The server also looks up the name you type for
  **Another machine**, so use a name or address the server knows.
- For **Remote**, **This Mac** is your Mac itself. Other machines can use the server's port only if the server's SSH
  settings allow it (`GatewayPorts`).
- Ports below 1024 on this Mac need administrator rights: use 1024 and above.
- Your Mac's end listens on 127.0.0.1 only, so other computers can't use your tunnel.
- All tunnels go off when the connection ends. When AirSCP reconnects by itself, it switches on again the ones that
  were on; after you reconnect, switch them on yourself.
- A tunnel can be edited only while it is off.

## If something goes wrong

- **“The port … is already in use on this Mac”**: another program or tunnel listens on it. Choose another port.


---

Source: https://kleash.github.io/airscp/commands/

# Snippets and Run Command

Run commands on a server without opening a terminal, save the ones you use often, or open a real terminal when you need
one.

(Picture: The Run a command sheet with df -h and its output)

## Pages

- [Run a command](https://kleash.github.io/airscp/commands/run-a-command.html)
- [Save commands as snippets](https://kleash.github.io/airscp/commands/snippets.html)
- [Open a terminal](https://kleash.github.io/airscp/commands/open-a-terminal.html)
- [The Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html): a shell inside AirSCP that knows files
- [See the commands AirSCP ran](https://kleash.github.io/airscp/commands/command-log.html)


---

Source: https://kleash.github.io/airscp/commands/run-a-command.html

# Run a command

Run one command on a server and read its output right in AirSCP.

## Steps

1. Select a connected host and choose **Host ▸ Run Command…** (<kbd>⇧⌘R</kbd>), or click **Run Command** in the
   toolbar.
2. Type the command, for example `df -h`. Or pick a saved one from **Snippets**.
3. Click **Run** (<kbd>⌘↩</kbd>).
4. Read the output. Error output is red. **Exit status 0** means it worked.
5. Click **Close**.

(Picture: The Run a command sheet: df -h, its output and Exit status 0)

## Run a script file

Select a script in the server pane and choose **File ▸ Run…**. Type arguments if it needs any, then click **Run** to
see its output, or **Run in Terminal**. AirSCP starts it with `sh` in its folder, whatever your login shell is, so an
unusual file name can't be misread.

## Tips

- The command runs in your account's login shell, without a terminal.
- For `sudo`, `top`, editors and anything that asks questions, click **Run in Terminal**. It opens Terminal, or the
  [Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html) when Settings says so.
- The output shows while the command runs. **Stop** ends a running command on the server too; what it printed stays.
- AirSCP keeps the last thousand lines of output and of error output.
- File-transfer-only (sftp) accounts can't run commands: the menu item is greyed out and says why.


---

Source: https://kleash.github.io/airscp/commands/snippets.html

# Save commands as snippets

A snippet is a command you run often, saved with a name. You choose the host each time you run it.

## Steps

1. Choose **Window ▸ Snippets**.
2. Click **+** to add a snippet. Type a **Name** and the **Command**.
3. Tick **Run in Terminal** for commands like `sudo` or `top`.
4. To run it: choose a host under **Run on**, then click **Run**. The output appears in a Run Command sheet.

(Picture: The Snippets window with four saved commands)

## Run a snippet on selected files

A snippet can name the files you select in a server pane:

| Placeholder | Becomes |
|---|---|
| `{file}` | each selected item's path: the command runs once per item |
| `{name}` | each selected item's name |
| `{files}` | all the selected paths, in one command |
| `{folder}` | the folder the pane shows |

1. Write the snippet, for example `gzip -k {file}` or `tar czf {folder}/backup.tgz {files}`.
2. In a server pane, select the files, right-click and choose **Run Snippet ▸** your snippet.
3. The output appears in a Run Command sheet (or Terminal, for **Run in Terminal**). The folder is listed again after.

AirSCP puts each name in quotes, so names with spaces or quotes are safe.

## Tips

- The Run Command sheet has your snippets in its **Snippets** pop-up.
- In the [Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html), **Insert Snippet** types one at the prompt without running it.
- Only snippets with a placeholder appear under **Run Snippet**. One with only `{folder}` runs without a selection.
- A snippet with a placeholder runs only from **Run Snippet**: the Snippets window's **Run**, Shortcuts and Ask AirSCP
  say so instead of running it.
- **−** deletes the selected snippet.


---

Source: https://kleash.github.io/airscp/commands/open-a-terminal.html

# Open a terminal

Open an ssh session to a host in Terminal or iTerm. It rides on AirSCP's open connection, so you don't log in again.

## Steps

- **Host ▸ Open Terminal** (<kbd>⌘T</kbd>), or the **Open Terminal** button in the toolbar.
- To start in the folder you are looking at: right-click in the server pane and choose **Open Terminal Here**
  (<kbd>⌥⌘T</kbd>).
- To use iTerm instead of Terminal: **AirSCP ▸ Settings… ▸ Open terminals in**.
- To have **Open Terminal Here** and **Run in Terminal** use AirSCP's own [Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html) instead:
  **AirSCP ▸ Settings… ▸ Open Terminal Here and Run in Terminal in the Terminal tab**.

(Picture: The toolbar's Open Terminal button above the Files tab)

## Tips

- macOS asks once whether AirSCP may control iTerm. Click **Allow**.
- **Host ▸ Copy ssh Command** (<kbd>⇧⌘C</kbd>) copies the ssh command line, to paste into any terminal. It is off for
  a host behind a proxy that needs a password (only AirSCP gives it): use **Host ▸ Open Terminal** for it. A proxy
  without a login is fine: the command reaches it with macOS's `nc`.


---

Source: https://kleash.github.io/airscp/commands/command-log.html

# See the commands AirSCP ran

AirSCP is a window on top of the ssh tools of macOS. The command log shows every command it ran for a host, as a line
you can copy and run yourself.

## Steps

1. Select a host and choose **View ▸ Show Command Log** (<kbd>⌥⌘L</kbd>), or click **Command Log** in the toolbar.
2. Each line shows the command, a tick or a cross for how it ended, and the time. Error output is under it.
3. **Copy** puts the command lines on the clipboard. **Clear** empties the log.

(Picture: The command log under the panes, with three ssh commands)

## Tips

- A command that runs again (for example a refresh) moves down instead of being listed twice.
- The log is handy when something fails: **Details** in an error shows ssh's own words too.


---

Source: https://kleash.github.io/airscp/commands/terminal-tab.html

# The Terminal tab

A shell on the server, inside AirSCP. It uses the host's connection, so there is no second login. Open as many shells
as you like, each in a tab of its own. It knows files: right-click a file name in the output to show, download or edit
it, drag it to Finder, and drop Finder files on it to upload them to the folder you are in. With bash and zsh it also
knows your commands: how each one ended, how long it took and what it printed, and it keeps them in a history you can
search.

## Steps

1. Connect to the host.
2. Click **Terminal** above the files, or choose **Host ▸ Terminal Tab** (<kbd>⌃⌘T</kbd>).
3. Type as in any terminal. Programs such as `less`, `vim`, `top` and `nano` work full screen.

## Open more shells in tabs

Click **+** above the terminal, or choose **Host ▸ New Terminal Tab** (<kbd>⇧⌘T</kbd>). The new shell starts in the
folder of the one you were looking at, on the same connection: no second login.

- Click a tab to show its shell. **Host ▸ Show Previous Terminal Tab** (<kbd>⇧⌘[</kbd>) and **Show Next Terminal Tab**
  (<kbd>⇧⌘]</kbd>) go through them.
- Each tab is named after its shell's folder, or the title the shell or a program gives it.
- To close the tab you see, click **×** or choose **Host ▸ Close Terminal Tab**. If a command is still running in it,
  AirSCP asks first (it can tell with bash and zsh, and for full-screen programs). The last tab stays: type `exit` to end
  its shell.

## See how each command ended

With bash and zsh, each command you run gets a small label at the right of its line when it ends:

- **✓ 0.4 s**: it worked, and took 0.4 seconds.
- **✗ exit 1 · 2.1 s**, in red: it failed, with exit status 1. A red bar runs down the left side of its output.

(Picture: The Terminal tab with two shells in tabs: cd, ls and grep marked ✓ with their time, and cat missing.txt marked ✗ exit 1 in red)

Right-click a command or its output:

- **Copy Output**: copies what the command printed.
- **Copy Command**: copies the command line. A command typed over several lines comes as you typed it, without the
  shell's `>` prompts.
- **Run Again**: types the command at the prompt and runs it. It waits until the prompt is empty. A command of
  several lines isn't typed again: use **Copy Command**, check it, and paste it.

Jump between commands with <kbd>⌘↑</kbd> and <kbd>⌘↓</kbd>, or with the arrow buttons at the top of the tab. The
command you jump to is tinted. <kbd>⌘↓</kbd> after the last one goes back to the bottom.

## Find text

Press <kbd>⌘F</kbd> (or click the magnifying glass) and type. Every match in the output and the scrollback is
highlighted, and the count shows how many there are. <kbd>Return</kbd> goes to the match above, <kbd>⇧Return</kbd> to
the one below. **Done** (or <kbd>Esc</kbd>) closes the find bar.

(Picture: The find bar with html: three matches highlighted in the output of ls, 3 of 3)

## Keep the Files tab in the same folder

Tick **Follow in Files** at the top of the tab. Each time you `cd` to another folder, the Files tab's server pane goes
there too. It goes only where the shell itself says it is: a folder that a program prints can't move it.

To go the other way, turn on **Open Terminal Here and Run in Terminal in the Terminal tab** in **AirSCP ▸ Settings…**.
Then a server folder's **Open Terminal Here** (<kbd>⌥⌘T</kbd>) goes to this tab. If the shell is at an empty prompt,
AirSCP types `cd` with the folder for you. If it is busy, or isn't bash or zsh (AirSCP can't tell when such a shell
waits), AirSCP opens a new tab in that folder instead, and never types into the busy one.

**Run in Terminal** (in **Run Command**, a snippet's option, **File ▸ Run…**, the Monitor's **Kill with sudo**) works the
same way with this setting: the command is typed and run at an empty prompt, or runs in a new tab.

The App Store version always works this way, without the setting.

## Insert a snippet

Click **Insert Snippet** at the top of the tab (or right-click ▸ **Insert Snippet**) and choose one. AirSCP types the
command at the prompt but doesn't run it: read it, change it if you need to, then press <kbd>Return</kbd>. Placeholders
such as `{file}` are typed as they are: replace them first. See [Save commands as snippets](https://kleash.github.io/airscp/commands/snippets.html).

## Go back to an earlier command

Click **History…** above the terminal (or right-click ▸ **History…**). It lists the commands you ran on this host,
newest first, from every tab and every earlier shell. Type to filter the list, use <kbd>↑</kbd> and <kbd>↓</kbd>, then
press <kbd>Return</kbd> (or click **Insert**): AirSCP types the command at the prompt but doesn't run it. Read it,
change it if you need to, then press <kbd>Return</kbd>.

(Picture: History…: the commands run on the host, newest first, with a filter, Clear History and Insert)

- Commands are kept when they end, with bash and zsh. A command you type with a space in front is not kept, as the
  shells themselves do.
- AirSCP keeps the last 1,000 commands of each host, each one once, on this Mac only. **Clear History** forgets them.
  The server's own shell history stays as it is.

## Insert a path from the server

Press <kbd>⌥⇥</kbd> (or click **Insert Path…**, or right-click ▸ **Insert Path…**). AirSCP lists the folder of the path
you are typing: `cat /var/log/sy` lists `/var/log`, `cat site/` lists `site` in the shell's folder, and nothing typed
lists the shell's folder. Type to filter, choose one, and press <kbd>Return</kbd>: AirSCP types its name in place of what
you typed, with quotes if it has spaces or other special characters. A folder comes with a `/`, so you can go on.

(Picture: Insert Path… while typing tail -n 20 ~/logs/: the names in /home/dev/logs)

This helps with long names, and with shells that can't complete names themselves. The list comes from the same
listing as the Files tab.

## Work with files from the output

Right-click a file or folder name that a command printed (`ls`, `find`, `grep -l`, a compiler's `file.c:12`):

- **Show in Files**: the Files tab shows it in the server's pane.
- **Download**: copies it to the Mac folder of the Files tab, through the transfer queue.
- **Edit in AirSCP**: opens it in AirSCP's editor. **Save** puts it back on the server.
- **Get Info**: its size, owner, permissions and dates.
- **Copy Path**: its full path on the server.

A name without a path is taken from the folder the shell is in.

## Drag a file to Finder

Select a file or folder name in the output (double-click it), then drag the selection to a Finder window or the
desktop. AirSCP downloads it there through the transfer queue, as when you drag from the Files tab.

## Upload by dropping files

Drag files from Finder onto the terminal. AirSCP uploads them to the shell's folder through the transfer queue, and
types their names at the prompt.

## How it knows your commands

When the server's shell is bash or zsh, AirSCP starts it with a few extra lines that mark each prompt, each command and
its end. Your own startup files (`.bash_profile`, `.profile`, `.zshrc` and the others) still run as before, and nothing
on the server is changed: the extra lines are in a temporary file that the shell deletes as soon as it starts. Other
shells (BusyBox `sh` on small servers, `fish`, `csh`) work as before, without labels, **Run Again**, **Follow in
Files** or the jumps.

With bash older than 4.4, commands show how they ended but not how long they took, and **Run Again** is off: use
**Copy Command** and paste it.

Completing names with <kbd>Tab</kbd> and going back through earlier commands with <kbd>↑</kbd> come from the server's
own shell, as in any terminal. **Insert Path…** and **History…** are AirSCP's, and work in every shell.

## Tips

- Select text by dragging; <kbd>⌘C</kbd> copies it and <kbd>⌘V</kbd> pastes. A double-click selects a word.
- Scroll up to see earlier output. **Clear Scrollback** (right-click) forgets it.
- <kbd>⌃C</kbd>, <kbd>⌃D</kbd> and the other Ctrl keys go to the shell. <kbd>⌘</kbd> shortcuts stay AirSCP's.
- When the shell ends (you typed `exit`, or the connection dropped), press <kbd>Return</kbd> in its tab for a new one.
- **Host ▸ Open Terminal** (<kbd>⌘T</kbd>) still opens Terminal or iTerm instead. See [Open a terminal](https://kleash.github.io/airscp/commands/open-a-terminal.html).

## If something goes wrong

- **“Connect to the host to open a shell here”**: the host isn't connected. Choose **Host ▸ Connect**.
- **“AirSCP can't tell which folder the shell is in”**: the server doesn't show it (no `/proc` and no `lsof`). Use
  full paths, or drop files on the Files tab's server pane instead.
- **No labels beside your commands**: the shell isn't bash or zsh, or your startup files replace the prompt hooks. Run
  `echo $SHELL` to see which shell the server starts.


---

Source: https://kleash.github.io/airscp/certificates/

# Certificates and keystores

**Tools ▸ Certificate Manager…** does the everyday certificate work without `openssl` or `keytool` commands. Open a
certificate, key or keystore, see what is in it and when it expires, check its chain, save it in the format another
system wants, or make a new certificate request. Everything happens on this Mac.

## Pages

- [Open and check certificates](https://kleash.github.io/airscp/certificates/open-and-check.html): details, expiry, which key goes with which certificate, the chain.
- [Convert and export](https://kleash.github.io/airscp/certificates/convert-and-export.html): PEM, DER, the chain, keys, PKCS#12, Java keystores, truststores.
- [Create a certificate or request](https://kleash.github.io/airscp/certificates/create.html): a new key with a certificate request (CSR) or a self-signed
  certificate.
- [See a server's certificate](https://kleash.github.io/airscp/certificates/server-certificate.html): what an HTTPS, LDAPS or mail server sends.

## Tips

- After each action AirSCP shows the `openssl` (or `keytool`) command that does the same. **Copy Command** puts it on
  the clipboard, to reuse it on a server.
- **Tools ▸ New Key Pair…** and **Tools ▸ Import PuTTY Key…** open the [Keys](https://kleash.github.io/airscp/keys/) window for SSH keys.


---

Source: https://kleash.github.io/airscp/certificates/open-and-check.html

# Open and check certificates

## Steps

1. Choose **Tools ▸ Certificate Manager…**.
2. Click **Open…**, or drop files on the window. It reads:
   - certificates: `.pem`, `.crt`, `.cer`, `.der`, one or many in a file;
   - chains: `.p7b`, `.p7c`;
   - PKCS#12: `.p12`, `.pfx`;
   - Java keystores: `.jks`;
   - private keys (RSA, EC, Ed25519; PKCS#1, SEC1, PKCS#8, encrypted or not), public keys and certificate requests.
3. A file with a password (PKCS#12, a keystore, an encrypted key) asks for it.
4. Select an item in the list to see its details.

## What the details show

(Picture: The Certificate Manager: a self-signed certificate for web-01.example.com and its key, with the certificate's details)

- **Subject** and **Issuer**: who the certificate is for, and who signed it.
- **Names (SAN)**: the host names and addresses it is valid for.
- **Valid until**: orange when it expires within 30 days, red once it has expired. The list's icons use the same
  colours.
- **Key usage**, **Extended key usage** and **Certificate authority**: what the certificate may be used for.
- **Private key**: whether a key that goes with it is open. A key's line says which certificate it goes with.
- **Issued by (open)**: the certificate that signed it, when that one is open too. The list shows each file's
  certificates in chain order, the server's own first.
- **SHA-256** and **SHA-1**: fingerprints, to compare with what someone sent you.

## Check a certificate's chain

1. Open the certificate, and the certificates that issued it if you have them.
2. Select the certificate and click **Verify…**.
3. Choose what to trust: **Authorities this Mac trusts**, or **A CA bundle file** (click **Choose…**).
4. Type a **Host name** to check that the certificate is for that name. Optional.
5. Click **Verify**.

(Picture: Verify web-01.example.com: against the authorities this Mac trusts, for the host name web-01.example.com)

The details say **Valid**, or why not: it has expired, the issuer is unknown, or the name doesn't match. Nothing is
fetched from the network.

## Tips

- Open the certificate, its key and the CA's certificate together: AirSCP matches them, and can then make a chain or a
  PKCS#12 file. See [Convert and export](https://kleash.github.io/airscp/certificates/convert-and-export.html).
- **Close File** takes a file out of the list. The file itself stays where it is.

## If something goes wrong

- **“That password didn't open it”**: check the password; PKCS#12 passwords are case-sensitive.
- **“The key … has a password of its own”**: in a Java keystore, a key can have another password than the store.
  Type the key's password.
- **“AirSCP doesn't read RC2-40 encryption”**: the file was made with `openssl pkcs12 -legacy` or by an old Windows.
  Export it again with AES or 3DES.
- **“AirSCP doesn't read JCEKS”**: convert the keystore to PKCS#12 with `keytool -importkeystore`.
- **“Not valid: unknown issuer”**: the certificates between it and the authority aren't open, or you don't trust that
  authority. Open the issuing certificates too, or choose the CA bundle that has the authority.


---

Source: https://kleash.github.io/airscp/certificates/convert-and-export.html

# Convert and export

Select an item in the Certificate Manager, then use the buttons below its details. Each asks where to save.

## For a certificate

- **Save PEM…**: Base64 text (`.pem`, `.crt`), what most Linux servers and tools want.
- **Save DER…**: binary (`.cer`, `.der`), for Windows and Java.
- **Save Chain…**: the certificate followed by its issuers (those open in the window), in one PEM file, as web servers
  such as nginx want.
- **Public Key…**: only its public key.
- **PKCS#12…**: the certificate, its private key and its chain in one file protected by a password (`.p12`, `.pfx`).
  Open the certificate's private key first.
- **JKS…**: the same in a Java keystore (`.jks`), for Java 8 and older. Newer Java reads PKCS#12 too.
- **Truststore…**: see [Make a truststore](#make-a-truststore).

## For a private key

- **Save Key…**: as PEM. Type a passphrase to encrypt it (AES-256), or leave it empty. **Traditional format** writes
  `BEGIN RSA PRIVATE KEY` (or `EC`) for older software.
- **PKCS#12…** and **JKS…**: the key with its certificate, when that is open.

## PKCS#12 options

- **Friendly name**: the name Windows and keystores show for the entry. Optional.
- **Compatible with older systems**: 3DES and SHA-1 instead of AES-256 and SHA-256. Only for Java 8 or Windows before
  2019, which can't open the modern file.

A Java keystore has an **Alias** (the entry's name, in lower case) and a **Password**, which protects the file and the
key in it.

## Convert between JKS and PKCS#12

1. Open the keystore and type its password.
2. Select the private key (or its certificate).
3. Click **PKCS#12…** to make a PKCS#12 file, or **JKS…** to make a Java keystore.

## Make a truststore

A truststore lists the certificate authorities an app trusts, such as a Java app's truststore.

1. Open the CA certificates the app should trust. A keystore or a bundle works too.
2. Select one of them and click **Truststore…**.
3. Tick the certificates that go in. CA certificates are ticked already.
4. Choose **PKCS#12 (.p12)** or **Java keystore (.jks)**, and type a password.
5. Click **Save…**.

Each entry is named after its certificate's common name. To add a certificate that isn't in the list, open its file
first.

## Tips

- Saved keys, PKCS#12 files and keystores are readable by you only.
- The line at the bottom shows the `openssl` or `keytool` command that makes the same file. **Copy Command** copies it.


---

Source: https://kleash.github.io/airscp/certificates/create.html

# Create a certificate or request

Make a new key with a certificate request (CSR) to send to a certificate authority, or with a self-signed certificate
for a test or internal server.

## Steps

1. Choose **Tools ▸ Certificate Manager…**.
2. Click **New…**.
3. Choose **Certificate request (CSR)** or **Self-signed certificate**.
4. Type the **Common name**: usually the server's host name, such as `web.example.com`.
5. In **Other names**, type more host names and IP addresses, with commas between them. Optional.
6. Fill in **Organization**, **Unit**, **City**, **State** and **Country** if your certificate authority wants them.
   **Country** is two letters, such as `US`.
7. Choose the **Key**. **RSA 2048** works everywhere.
8. For a self-signed certificate, type how many days it is **Valid for**.
9. Type a **Key passphrase** to encrypt the key file, or leave it empty.
10. Click **Create…** and choose where to save. The key is saved beside it, as a `.key` file.

The new request (or certificate) and its key appear in the list.

(Picture: New: a self-signed certificate for web-01.example.com, also for www.example.com and 203.0.113.10)

## What a self-signed certificate has

- The common name and the other names, so browsers can check them.
- It is not a certificate authority: it can't sign other certificates.
- It is for a TLS server: server authentication, and the key usages for it.
- A SHA-256 signature.

## Tips

- Send the request (`.csr`) to your certificate authority. Keep the `.key` file: the certificate they send back works
  only with it. Then open both and make a PKCS#12 or JKS file: see [Convert and export](https://kleash.github.io/airscp/certificates/convert-and-export.html).
- AirSCP never saves over a file that is already there.
- Apple devices refuse server certificates valid for more than 825 days.
- The line at the bottom shows the `openssl req` command that makes the same files. It asks for the passphrase itself.
  **Copy Command** copies it.

## If something goes wrong

- **Create… is dimmed**: hold the pointer over it. It says what is missing, such as the common name.
- **“… isn't a host name or an IP address”**: Other names takes host names (letters, digits, hyphens and dots, `*.` at
  the start for a wildcard) and IP addresses only.
- **“Nothing saved: … already exists”**: a file with that name is in the folder already. Choose another name.


---

Source: https://kleash.github.io/airscp/certificates/server-certificate.html

# See a server's certificate

Check what certificate a website, LDAP or mail server sends, and whether this Mac trusts it.

## Steps

1. Choose **Tools ▸ View Server Certificate…** (or click **Server…** in the Certificate Manager).
2. Type the server, with its port when it isn't 443: `example.com`, `ldap.example.com:636`, `mail.example.com:465`.
3. Click **View**.

The server's certificates appear in the list, its own first, with a line that says whether this Mac trusts them for
that name, and why not.

## Tips

- Only the TLS handshake happens: nothing else is sent to the server.
- Save the server's certificates like any other: for example **Save Chain…** to give a Java truststore the server's
  CA.
- The command shown is `openssl s_client`, to look again from a server that has openssl.

## If something goes wrong

- **“Can't get the certificate”**: the server isn't reachable from this Mac on that port, or it doesn't speak TLS
  there (STARTTLS ports such as 25 and 587 start in plain text and aren't read).
- It stays at **“Connecting…”**: a firewall app on this Mac (such as LuLu or Little Snitch) may be asking whether
  AirSCP may connect. Allow it.


---

Source: https://kleash.github.io/airscp/keys/

# Keys

An SSH key pair lets you log in without typing a password. The **Keys** window lists your keys and makes new ones.

## Steps

1. Choose **Window ▸ Keys**.
2. You see every private key in `~/.ssh`, with its type, comment and fingerprint.
3. Select a key for the buttons below the list:
   - **Copy Public Key**: the public key, to paste into a server or a web console. Its menu has other formats: SSH2
     (RFC 4716) and PEM (PKCS#8).
   - **Install on Host…**: put the public key on a server. See [Put your key on a server](https://kleash.github.io/airscp/keys/install-a-key.html).
   - **Export for PuTTY…**: a `.ppk` copy for Windows tools. See [Use your PuTTY keys](https://kleash.github.io/airscp/keys/putty-keys.html).
   - **Add to Agent**: keep the key in the ssh agent, with its passphrase in your Keychain.

(Picture: The Keys window with two keys, their type, comment and fingerprint)

## Pages

- [Make a new key pair](https://kleash.github.io/airscp/keys/new-key-pair.html)
- [Put your key on a server](https://kleash.github.io/airscp/keys/install-a-key.html)
- [Use your PuTTY (.ppk) keys](https://kleash.github.io/airscp/keys/putty-keys.html)

## Tips

- **Other Key File…** adds a key that lives somewhere else.
- A key that needs its passphrase before it can be read shows “type unknown”.
- **Settings ▸ Keys** sets the folder for new keys: `~/.ssh` by default, where ssh finds them by itself.


---

Source: https://kleash.github.io/airscp/keys/new-key-pair.html

# Make a new key pair

Make a key in a few clicks, without the command line. Then put it on your servers to log in without a password.

## Steps

1. Choose **Window ▸ Keys** and click **New Key Pair…**. (Or, in a host's settings, choose **Log in with ▸ Generate
   New Key…**.)
2. Leave **Type** on **Ed25519 (recommended)**: modern, short and fast; every current server takes it.
3. Check the **Name**. AirSCP suggests one that never overwrites a key you have.
4. Optional: a **Passphrase** protects the key if someone copies the file. Tick **Remember the passphrase in
   Keychain** so you don't have to type it.
5. Click **Generate**.

(Picture: The New Key Pair sheet: Ed25519, a name, the folder, a comment and an optional passphrase)

AirSCP shows the new key's fingerprint and its public key. The public key is already on your clipboard (you can turn
that off with **Copy the public key after generating**).

(Picture: Key pair created: the fingerprint, the public key and Copy Public Key, Install on Host and Export buttons)

Next: **Install on Host…** puts the key on a server. See [Put your key on a server](https://kleash.github.io/airscp/keys/install-a-key.html).

## Key types

| Type | When to choose it |
|---|---|
| **Ed25519 (recommended)** | Almost always. |
| **ECDSA 256, 384 or 521** | When a server or policy asks for ECDSA. |
| **RSA 2048, 3072 or 4096** | Old servers and network devices. 3072 or more is recommended. |
| **Ed25519-SK / ECDSA-SK** | A hardware security key such as a YubiKey. Shown only when your Mac's ssh supports it. |

DSA isn't offered: it is obsolete, and modern servers refuse it.

## Advanced

- **Private key format**: **OpenSSH (default)**; **PEM** for older tools; **PKCS#8**.
- **Public key format**: **OpenSSH (one line)** for most servers; **SSH2 (RFC 4716)** for some commercial servers and
  network devices; **PEM (PKCS#8)** for tools that take a standard public key.

## Tips

- **Change…** saves the key in another folder.
- The passphrase goes to ssh-keygen only, never into a command line.
- The **?** button in the sheet opens this page.


---

Source: https://kleash.github.io/airscp/keys/install-a-key.html

# Put your key on a server

The server must know your public key before you can log in with it. AirSCP adds it for you (like `ssh-copy-id`).

## Steps

1. Choose **Window ▸ Keys** and select the key.
2. Click **Install on Host…**.
3. Choose the **Host**.
4. Click **Install**. AirSCP connects, asks the server's password once, and adds the public key to the account's
   `~/.ssh/authorized_keys`.
5. Set the host to use the key: **Host ▸ Edit… ▸ Log in with**.

(Picture: Install id_ed25519 on a host: the Host pop-up set to web-01)

## Tips

- Accounts that allow file transfers only (sftp) work too: AirSCP adds the key over sftp.
- Made the key from a host's settings? Its result sheet has **Install on This Host** and **Use for This Host**.
- Your server has a web console instead (cloud providers)? Use **Copy Public Key** and paste it there.


---

Source: https://kleash.github.io/airscp/keys/putty-keys.html

# Use your PuTTY (.ppk) keys

Coming from Windows or PuTTY? Your keys are `.ppk` files. AirSCP turns them into keys that ssh on the Mac can
use, and back. Nothing else needs to be installed.

## Import a .ppk key

1. Choose **Window ▸ Keys** and click **Import Key…** (or drop the `.ppk` file on the Keys window).
2. If the `.ppk` file has a passphrase, type it.
3. Check the **Name** of the new key. Keep the same passphrase, or choose a new one (empty for none).
4. Click **Import**. The key appears in the list, ready to use.

(Picture: The Import web.ppk sheet: the new key's name, folder and passphrase)

A host's **Log in with ▸ Choose a Key File…** accepts a `.ppk` file too: it is imported first.

## Export a key for PuTTY

1. Select a key in the Keys window and click **Export for PuTTY…**.
2. Optional: a passphrase for the `.ppk` file.
3. Click **Export…** and choose where to save it.

(Picture: Export as a PuTTY key: an optional passphrase for the .ppk file)

The `.ppk` file is in PuTTY's key format version 3, which PuTTY 0.75 (2021) and later read. Update an older PuTTY to
use it.

## Tips

- RSA, ECDSA and Ed25519 keys work, encrypted or not. Import reads PPK version 2 and 3.
- The `.ppk` file and your key stay as they are: AirSCP writes new files and never overwrites one.
- The unencrypted key exists only for a moment, in a private temporary folder that AirSCP wipes.

## If something goes wrong

- **A wrong passphrase** or **a damaged file** is shown in red in the sheet. AirSCP checks the file's integrity (its
  MAC) before using it.


---

Source: https://kleash.github.io/airscp/settings.html

# Settings and appearance

Choose light or dark mode, your terminal app, your downloads folder and a few defaults. Open **AirSCP ▸ Settings…**
(<kbd>⌘,</kbd>). Every change applies at once.

(Picture: Settings: Appearance, Files and Security)

## Appearance

**System** (the default) follows your Mac's light or dark mode. **Light** or **Dark** keeps AirSCP in one of them.

- **Light** is the Paper look: white panes on a grey background, and black for the selected row, the active tab and the
  main buttons.
- **Dark** is the Night Harbor look: a deep blue-grey, with a colour for each kind of thing (servers blue, Remote
  Desktop purple, proxies orange) and glowing dots for connected servers.

Your Mac's accent colour, **Increase contrast** and **Reduce transparency** (System Settings ▸ Accessibility ▸ Display)
still apply. With Increase contrast on, the dark look drops its blue tint.

(Picture: AirSCP's window; it follows the appearance you choose)

## Files

| Setting | What it does |
|---|---|
| **Open terminals in** | Terminal (default) or iTerm, for Open Terminal, Run in Terminal and Kill with sudo. |
| **Open Terminal Here and Run in Terminal in the Terminal tab** | Off by default. On: a server folder's **Open Terminal Here** and **Run in Terminal** go to the host's [Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html) in AirSCP instead: typed at an empty prompt, else in a new tab. |
| **Downloads folder** | Where **Download To…** starts, and where **Download as .tar.gz** puts the archive when the other pane isn't this Mac. Drags and the Download button go to the folder shown. |
| **Show hidden files in new panes** | Off by default. Each pane can still switch with <kbd>⇧⌘.</kbd>. |
| **Copied files keep their original date** | Off by default: copies are dated now. On: they keep the file's own date (`scp -p`). |
| **Verify transfers with SHA-256** | Off by default. On: each copied file is compared with the original once it arrives. See [Check a copy with its checksum](https://kleash.github.io/airscp/transfers/verify-checksums.html). |
| **Ask before deleting on a server** | On by default. |
| **Always calculate folder sizes** | Off by default: folders show “—” until you click **Σ**. |

The App Store version has neither terminal setting: it always uses the Terminal tab.

## Security

How new hosts check their server's key, and new desktops their server's certificate. **Ask** unless you change it. See
[Self-signed certificates and corporate networks](https://kleash.github.io/airscp/connecting/self-signed-certificates.html).

## Keys

**New keys go in**: the folder where New Key Pair and Import Key save keys. `~/.ssh` by default, where ssh finds them by
itself.

**SSH folder** (the App Store version only): the folder ssh uses for your keys, known hosts and config. Click
**Choose…** and choose `~/.ssh` (the panel opens there). Until you do, AirSCP keeps its own. See
[The App Store version](https://kleash.github.io/airscp/getting-started/install.html#the-app-store-version).

## Apple Intelligence

**Use Apple Intelligence for Ask AirSCP and Explain**: on by default, on a Mac that has it. Answers come from Apple's
model on this Mac. See [Shortcuts, Siri & Apple Intelligence](https://kleash.github.io/airscp/shortcuts-and-ai.html).

## Agents

**Allow AI agents to control AirSCP (MCP)**: off by default. See [AI agents (MCP)](https://kleash.github.io/airscp/ai-agents.html).

**Ask before agents change things**: on by default. Before an agent deletes, copies or runs something, a small window
asks you: **Deny**, **Allow Once** or **Allow for 15 Minutes**. Agents can't turn it off. See
[Allow or deny what an agent changes](https://kleash.github.io/airscp/ai-agents.html#allow-or-deny-what-an-agent-changes).

## Advanced

**Debug logging**: off by default. On, AirSCP writes a detailed log of connections and transfers, to help find what
went wrong. Turn it off when done. See [Turn on debug logs](https://kleash.github.io/airscp/troubleshooting.html#turn-on-debug-logs).

(Picture: Settings: Advanced, with Debug logging)

## Tips

- The **?** button at the bottom of Settings opens this page.


---

Source: https://kleash.github.io/airscp/ai-agents.html

# Let AI agents use AirSCP (MCP)

AI agents such as Claude Code, Codex CLI or Gemini CLI can drive AirSCP the way you do: the same menus, buttons and
questions, and AirSCP's own screenshots. AirSCP is an MCP server for them. It is off until you turn it on.

## Steps

1. Open **AirSCP ▸ Settings…** and turn on **Allow AI agents to control AirSCP (MCP)**.
2. Settings shows the command that adds AirSCP to Claude Code. Click **Copy** and paste it into Terminal. It looks like
   this:

   ```sh
   claude mcp add airscp -- /Applications/AirSCP.app/Contents/MacOS/AirSCP --mcp
   ```

   Other MCP clients take the same program with `--mcp`. Codex: `codex mcp add airscp -- /Applications/AirSCP.app/Contents/MacOS/AirSCP --mcp`.

   For Claude Code there is also a plugin, with a skill that teaches Claude how to use AirSCP. In Claude Code, type
   `/plugin marketplace add kleash/airscp`, then `/plugin install airscp@airscp`.
3. Ask your agent to do something in AirSCP, for example “upload the build folder to web-01”.

(Picture: Settings: Allow AI agents to control AirSCP (MCP), turned on)

## Allow or deny what an agent changes

Before an agent changes something, AirSCP asks you. A small window shows what the agent wants to do, over every app:

- **Deny** (the default, also <kbd>Return</kbd> and <kbd>Esc</kbd>): the agent is told that you said no.
- **Allow Once**: just this change.
- **Allow for 15 Minutes**: this change, and every change agents ask for in the next 15 minutes, without asking again.

If nobody answers within 45 seconds, nothing is done, and the agent is told so.

AirSCP asks before an agent:

- deletes, replaces or renames files, or copies them to or from a server (uploads, downloads, drops, Synchronize);
- zips or unpacks files on S3 storage, or makes a presigned link that lets anyone download a file;
- opens a file in another app;
- changes files' permissions or owners (Make Executable too), or puts a key on a server or in the ssh agent;
- switches a tunnel on or off;
- runs a command, a file or a snippet, types into a Terminal tab, or closes a tab whose command still runs;
- kills a process, cancels, retries or resumes transfers, disconnects or quits;
- types, presses keys or clicks on a Windows desktop.

It doesn't ask when an agent only looks, selects, goes to a folder, opens AirSCP's own windows or fills in their fields.
When AirSCP asks a question of its own first (Delete asks “Delete …?”), the window comes when the agent answers it.

To turn these questions off, open **AirSCP ▸ Settings…** and turn off **Ask before agents change things**. Agents
can't turn it off.

(Picture: Settings: Ask before agents change things, turned off)

## See what an agent does

- The sidebar's footer shows **Agent control on**. While an agent acts, its dot pulses and the footer names the agent and
  its last action.
- Hover over it to see who is connected and since when. Click it for the last 20 actions in plain words, with **Turn
  Off Agent Control** and **Settings…**.
- While AirSCP asks you about a change, the footer says **Waiting for your OK**. After **Allow for 15 Minutes**, the
  hover text says until when agents may change things without asking.

(Picture: The agent's recent actions: it dropped three files on the server pane, set a speed limit and selected a file)

## Windows desktops

An agent can work in a Remote Desktop too. It works the way a careful person at the keyboard does:

- **Keys first.** It opens File Explorer with <kbd>⊞</kbd> <kbd>E</kbd>, goes to a folder through the address bar
  (<kbd>Alt</kbd> <kbd>D</kbd>, the path, <kbd>Return</kbd>) and runs programs with <kbd>⊞</kbd> <kbd>R</kbd>.
  Keys don't miss.
- **Clicks where no key reaches.** The agent clicks in the pixels of the desktop picture AirSCP gives it, so the
  window's size, a Retina screen or full screen don't move its clicks. After each click AirSCP shows it a close-up of
  the spot with a red cross, so it can see what it hit.

## Safe by design

- Only programs of your own user account on this Mac can connect, through a private socket with a secret that changes
  at every launch.
- Agents never see saved passwords: password fields read as •••, and no tool reads the Keychain.
- AirSCP's questions stay in the way: Delete still asks, and the agent has to answer.
- Changes wait for your OK (see [Allow or deny what an agent changes](#allow-or-deny-what-an-agent-changes)).
- Turning the setting off closes the connection at once.

## For agents and scripts

- The agent gets AirSCP's guide when it connects, and a `guide` tool for the details. **Help ▸ Agent Guide** shows the
  same text.
- Agents go to a folder by its path and open a file or folder by its name (the `go` and `open` tools). You see the
  panes move as they work, and they never need to click in the file list.
- From a shell: `AirSCP --agent snapshot`, `AirSCP --agent menu path='Host > Connect'`,
  `AirSCP --agent screenshot --out shot.png`.
- All of this help as plain text for agents: [llms.txt](https://kleash.github.io/airscp/llms.txt) and
  [llms-full.txt](https://kleash.github.io/airscp/llms-full.txt).


---

Source: https://kleash.github.io/airscp/shortcuts-and-ai.html

# Shortcuts, Siri and Apple Intelligence

## Shortcuts and Siri

AirSCP's actions are in the **Shortcuts** app, in Spotlight and for Siri:

- **Connect to Host**: opens AirSCP and connects to a saved host. Say “Connect to web-01 with AirSCP”.
- **Open a Shell on Host**: connects and shows the host's [Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html).
- **Open Remote Desktop**: connects to a saved Windows desktop.
- **Upload Files**: uploads files and folders from your Mac to a server folder. Say “Upload to web-01 with AirSCP”.
- **Download Files**: downloads server files and folders to a folder on your Mac (your download folder if you leave
  it empty).
- **Find Files**: finds files on a server by name, like `*.log`, and gives the list to the next action.
- **Run Snippet**: runs one of your [snippets](https://kleash.github.io/airscp/commands/snippets.html) on a host (one without placeholders such as
  `{file}`: those run on files you select).
- **Start Tunnel** and **Stop Tunnel**: switch one of a host's [tunnels](https://kleash.github.io/airscp/tunnels.html) on or off.
- **Open Favourite Folder**: connects and shows one of a host's favourite folders.
- **Disconnect All**: disconnects everything AirSCP is connected to.
- **Get Transfer Status**: says how the transfers are going, to use in a shortcut.

Open the Shortcuts app and search for AirSCP to put them in your own shortcuts, or give them a key. They do exactly what
the menus do: AirSCP still asks before it replaces a file, and asks for a password the way it always does.

**Spotlight** (macOS 15 or later) finds your saved hosts and Remote Desktops by name: choose one to open it in AirSCP.

## Ask AirSCP (Apple Intelligence)

On a Mac with Apple Intelligence (Apple silicon, macOS 26 or later, Apple Intelligence turned on):

- **Help ▸ Ask AirSCP…** (<kbd>⌥⌘K</kbd>): ask in your own words, e.g. “Why can't I connect to web-01?” or “How do I
  upload a folder without node_modules?”, and click **Ask**.
- **Do It…** in the same window: say what you want done, e.g. “Upload ~/Sites/site to web-01 in /var/www, leave out
  node_modules” or “Start the 8080 tunnel on db and find big log files in /var/log”. AirSCP shows the steps as
  sentences first. **Nothing runs until you click Run**, and AirSCP still asks before it replaces or deletes anything.
  A step that names a host, snippet or tunnel you don't have says so, and Run stays off.
- A failed connection's banner has **Explain…**: it asks what the error means and what to try.
- **Monitor** has **Explain…**: is anything wrong with the server's CPU, memory, disks or busiest processes?
- The **Command Log** has **Summarize…**: what did AirSCP just do, and did anything fail?
- In **Window ▸ Snippets**, **Explain…** says what a command does, and whether it is risky, before you run it.
- **Suggest…** (the sparkles button) next to a host's **Other ssh options**, **Leave out**, Find Files' pattern and the
  Permissions octal: describe what you want (“keep the connection alive through a firewall”, “everyone can read, only I
  can write”) and AirSCP shows the value. It goes into the field only when you click **Use**.

The answer comes from Apple's model **on this Mac**: your question and a short summary of the host in front (its name,
address, route, state, the last error and the commands AirSCP ran) never leave it. Do It… also tells it the names of
your saved hosts, Remote Desktops, snippets and tunnels. Passwords, keys and file contents are
never part of it. **What AirSCP tells it**, in the Ask window, shows that summary.

AI can be wrong: check what it suggests before you act on it.

## Tips

- **Settings ▸ Apple Intelligence** turns Ask AirSCP, Do It…, Explain, Summarize and Suggest off for AirSCP. The
  buttons only show when Apple Intelligence can answer.
- When Help ▸ Ask AirSCP… is greyed out, point at it to see why (for example, Apple Intelligence is off in System
  Settings ▸ Apple Intelligence & Siri).


---

Source: https://kleash.github.io/airscp/troubleshooting.html

# Troubleshooting

AirSCP explains each error in plain words and says what to do next. **Details** shows ssh's own words. Here are the
common ones.

(Picture: Can't connect to old-server: The server refused the connection. Check the port and that its SSH server is running.)

## Connecting

| Message | What to do |
|---|---|
| **The server refused the connection** | Check the port, and that the server's SSH service is running. |
| **The server can't be reached from this network** | Check Wi-Fi or VPN. Behind another server? Set **Connect through** in its settings. |
| **The server didn't accept the user name or password** | Check the user name (**Host ▸ Edit…**), then try the password again. |
| **The server didn't accept the login; it allows: publickey** | The server wants a key. Choose one under **Log in with**, or install one: **Window ▸ Keys**. |
| **Too many authentication failures** | Choose one key under **Log in with**, or add `IdentitiesOnly=yes` in [Extra ssh settings](https://kleash.github.io/airscp/connecting/extra-ssh-settings.html). |
| **no matching key exchange** / old RSA keys | An old server. Add the matching line from [Extra ssh settings](https://kleash.github.io/airscp/connecting/extra-ssh-settings.html). |
| **The server's host key was not accepted** | You clicked Cancel at the trust question. Connect again and click **Trust** if the fingerprint is right. |
| **The server's key has changed** | Ask the server's admin. See [Trust a server the first time](https://kleash.github.io/airscp/connecting/trust-a-server.html). |
| **The proxy rejected the user name or password** | Check the proxy's user name in **Host ▸ Proxies…**, then connect again. |

## Files and transfers

| Message | What to do |
|---|---|
| **This account allows file transfers (sftp) only** | Files work; commands, Monitor and Run don't on that account. |
| **You don't have permission to write in that folder** | Choose another folder, or ask the server's admin. |
| **The file or folder doesn't exist (any more)** | Refresh the list (<kbd>⌘R</kbd>). |
| **Some items couldn't be copied; the rest were** | **Show Details…** names them; **Retry** runs the transfer again. |
| A transfer says **stalled** | The connection is slow or stuck. Wait, or Cancel and Retry. |

## Remote Desktop

| Message | What to do |
|---|---|
| **The user name or password is incorrect** | A company account needs its domain (the Domain field, or `DOMAIN\user`). |
| **AirSCP couldn't reach the server** | Check the address, that Remote Desktop is on in Windows, and your VPN. Allow AirSCP on the local network if macOS asks. |
| **The certificate of … has changed** | Trust it only if you know why it changed. |
| **Windows' policy blocks the shared folder** | The Windows computer doesn't allow drive redirection (Group Policy **Do not allow drive redirection**): `\\tsclient` is empty there. Copy and paste files instead, or ask its administrator. See [Copy files](https://kleash.github.io/airscp/remote-desktop/copy-files.html). |
| **Press ⌃⌘F to leave full screen** | The Windows desktop fills the screen. Press <kbd>⌃⌘F</kbd>, or move the pointer to the top of the screen and choose **View ▸ Exit Full Screen**. |

## Turn on debug logs

When a connection fails and the message doesn't say enough (often through a proxy or a jump host), the debug log shows
each step: which server answered, what the proxy said, and where it stopped.

1. Choose **Help ▸ Turn On Debug Logging**. Or turn on **Debug logging** in **AirSCP ▸ Settings…** (under
   **Advanced**), or click **Turn On Debug Logging and Try Again** in the error message.
2. Connect again, or do again what failed.
3. Choose **Help ▸ Show Debug Log in Finder**. The file is `AirSCP-debug.log` in `~/Library/Logs/AirSCP`.
4. Attach the file to your report (**Help ▸ Report a Problem**). **Help ▸ Copy Diagnostics** copies your versions and
   the last lines of the log.
5. Turn it off when you are done: click **Turn Off** next to **Debug logging on** at the bottom of the sidebar, or
   choose **Help ▸ Turn Off Debug Logging**.

(Picture: With debug logging on, the sidebar says so and an error offers Show Debug Log)

- Look for the line **Couldn't connect: it stopped at …**. It names the step that failed: the proxy, the jump
  host, or the server.
- The log never holds passwords, passphrases or file contents. It stays on your Mac: AirSCP sends it nowhere.
- It keeps at most 10 MB, plus one older file (`AirSCP-debug.1.log`).

## macOS questions

- **AirSCP wants to use your Keychain**: AirSCP reads a saved password. Choose **Always Allow**. AirSCP waits for your
  answer.
- **AirSCP would like to find devices on your local network**: needed for servers and Windows computers on your
  network. Choose **Allow**. Changed your mind later? **System Settings ▸ Privacy & Security ▸ Local Network**.
- **AirSCP wants to control iTerm**: needed to open sessions in iTerm. Choose **Allow**.

## Still stuck?

Choose **Help ▸ Report a Problem**. It opens a short form on GitHub with your AirSCP and macOS versions filled in.
Attach the [debug log](#turn-on-debug-logs). The command log (**View ▸ Show Command Log**) helps too: copy the failing
line into the report, but remove anything private.


---

Source: https://kleash.github.io/airscp/faq.html

# Questions and answers

(Picture: AirSCP's window with a server's files and transfers)

**Is AirSCP free?**
Yes. It is free and open source (Apache 2.0). There is no account and no subscription.

**What does it need?**
macOS 13.1 or later, on Apple silicon or Intel. Nothing else: AirSCP uses the `ssh`, `scp` and `sftp` tools that
come with macOS, and has Remote Desktop built in.

**Does it change my ~/.ssh/config?**
No. AirSCP reads it (aliases keep working) and never changes it. New keys go into `~/.ssh` only when you make them.

**Where are my hosts saved?**
In `~/Library/Application Support/AirSCP/airscp.json`. Passwords are in your login Keychain, never in that file.

**Can I see the commands it runs?**
Yes: **View ▸ Show Command Log**. Every line can be copied and run in Terminal. See
[See the commands AirSCP ran](https://kleash.github.io/airscp/commands/command-log.html).

**Does it work with Windows servers?**
Yes, in two ways. The built-in [Remote Desktop](https://kleash.github.io/airscp/remote-desktop/) opens Windows desktops. And Windows' own
OpenSSH server works for browsing and transfers. Commands, compress and the monitor need a Linux or Mac server.

**Does it support FTP or telnet?**
No. AirSCP is for SSH (scp and sftp) and Remote Desktop. It can connect through HTTP and SOCKS5 proxies: see
[Connect through a proxy](https://kleash.github.io/airscp/connecting/proxies.html).

**Can I sync my hosts between Macs?**
Not automatically. Use **File ▸ Export Hosts…** and **Import Hosts…**. See
[Move your hosts to another Mac](https://kleash.github.io/airscp/connecting/move-to-another-mac.html).

**Can it keep a folder in sync all the time?**
No. [Synchronize](https://kleash.github.io/airscp/synchronize.html) runs when you ask it to.

**Is there a built-in terminal?**
Not yet. **Open Terminal** opens Terminal or iTerm on the host, without logging in again.

**My server is behind another server. Can AirSCP reach it?**
Yes, through one jump host. See [Connect through a jump host](https://kleash.github.io/airscp/connecting/jump-hosts.html).

**Can AI agents use it?**
Yes, when you allow it. See [AI agents (MCP)](https://kleash.github.io/airscp/ai-agents.html).

**What's not included?**
Mosh, serial connections, editing files as root, jump chains of more than one hop, resuming folder transfers, and
Remote Desktop audio, printers, smart cards and multiple monitors.


---

Source: https://kleash.github.io/airscp/privacy-security.html

# Privacy and security

AirSCP keeps your servers, files and passwords on your Mac.

(Picture: A password question with Remember in Keychain)

## What stays on your Mac

- **No account, no tracking**: AirSCP sends nothing about you or your use anywhere. It connects only to the servers and
  computers you choose.
- **Hosts and settings**: in `~/Library/Application Support/AirSCP/airscp.json` (the App Store version keeps them in
  its own folder, `~/Library/Containers/com.kleash.airscp`).
- **Passwords**: in your login Keychain, one item named `com.kleash.airscp`, and only when you tick **Remember**. An S3
  connection's secret key is always kept there.
- **Terminal history**: the commands you ran in a host's Terminal tab, in the `history` folder next to `airscp.json`,
  which only you can read. **Clear History** or deleting the host removes it.
- **Exports** (File ▸ Export Hosts…) never contain passwords or private keys.

## How connections are protected

- AirSCP uses the OpenSSH tools that come with macOS. Your keys never leave your Mac.
- New servers are trusted only after you check their fingerprint (**Ask**, the default). A changed server key is
  refused. See [Trust a server the first time](https://kleash.github.io/airscp/connecting/trust-a-server.html).
- A host or desktop whose checks you turned off shows an orange shield, so it is never forgotten. See
  [Self-signed certificates and corporate networks](https://kleash.github.io/airscp/connecting/self-signed-certificates.html).
- Passwords reach ssh through AirSCP's own private channel, never on a command line, where other programs could read
  them. Saved passwords are given only to the ssh processes AirSCP started.
- Copies arrive under a temporary name and replace a file only when they are complete.

## AI agents

- Off by default. When on, only programs of your own user account on this Mac can connect.
- Agents never see saved passwords, and AirSCP's questions (Delete, Trust) stay in the way.
- The sidebar shows when an agent is connected and what it did. See [AI agents (MCP)](https://kleash.github.io/airscp/ai-agents.html).

## Apple Intelligence

- Ask AirSCP and Explain use Apple's on-device model: nothing is sent to Apple or anyone else.
- The model gets your question and a short summary of the host in front, never passwords, keys or file contents.
- **Settings ▸ Apple Intelligence** turns it off.

## Report a security problem

Please don't open a public issue: follow the security policy (`SECURITY.md`) in
[AirSCP's repository](https://github.com/kleash/airscp).


---

Source: https://kleash.github.io/airscp/whats-new.html

# What's new

## AirSCP 1.4.0

- **Disk Usage**: **File ▸ Disk Usage…** shows what takes the room below a folder, on a server or on this Mac. While
  it scans, a bar shows how far it is, the files it finds show with their sizes, and the rings and the list grow as
  the sizes add up. Point at a ring to see what it is; click a folder's ring, or double-click it in the list, to go
  into it. **Largest Files** lists the 200 biggest files below. Select what you don't need and **Delete…** it (on this
  Mac it goes to the Trash), or **Show** it in the pane or in Finder. See [Disk Usage](https://kleash.github.io/airscp/disk-usage.html).

## AirSCP 1.3.0

- **Amazon S3 and S3-compatible storage**: **File ▸ New S3 Connection…** saves an Amazon S3, MinIO, Cloudflare R2,
  Backblaze B2, Wasabi or Ceph account. Its buckets open in the Files tab like a server's folders: browse, drag files
  in and out, rename, move, copy, delete, edit, Get Info, Find Files and Synchronize. Big files go in parts that
  survive a pause. The secret key stays in your Keychain. See [S3 storage](https://kleash.github.io/airscp/s3/).
- **Import from ~/.aws**: **File ▸ Import from ~/.aws…** makes S3 connections from the AWS command line tool's
  profiles.
- **Links to files on S3**: right-click ▸ **Copy S3 Link** or **Copy Presigned Link…** (an `https` link anyone can open
  until it expires).
- **Zips on S3**: **Download as .zip…**, **Compress…** in the bucket and **Extract Here**, made on your Mac. See
  [Zip and extract](https://kleash.github.io/airscp/s3/zip-and-extract.html).
- **Terminal tabs**: open several shells on one host in the Terminal tab, each in a tab of its own, all on the same
  connection (no second login). Click **+** or choose **Host ▸ New Terminal Tab** (<kbd>⇧⌘T</kbd>); <kbd>⇧⌘[</kbd> and
  <kbd>⇧⌘]</kbd> go through them, and closing a tab asks first while a command still runs in it. See
  [The Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html).
- **Command history**: **History…** lists the commands you ran on a host (bash and zsh), newest first. Type to filter,
  and AirSCP types the one you choose at the prompt without running it. It stays on this Mac; **Clear History** forgets it.
- **Insert Path…** (<kbd>⌥⇥</kbd>): pick a file or folder name from the server's folder you are typing, and AirSCP types
  it at the prompt, quoted where it needs it. Handy for long names and shells that can't complete names.
- **Drag to Finder**: select a file name in the Terminal tab's output and drag it to Finder to download it.
- **Open Terminal Here and Run in Terminal** can both go to the Terminal tab (Settings): at an empty prompt AirSCP types
  the `cd` or the command there; while the shell is busy, it opens a new tab instead of typing into it.
- **In the Mac App Store**: the same AirSCP, in Apple's sandbox. You choose the folders it may open, starting with your
  SSH folder, and terminals open in the Terminal tab. See [The App Store version](https://kleash.github.io/airscp/getting-started/install.html#the-app-store-version).
- **Apple Intelligence** gives shorter answers that stick closer to AirSCP's real menus and buttons. The Command
  Log's **Summarize…** now sees which commands failed, and **Do It…** keeps closer to the steps you ask for.
- **AI agents** work with S3 storage and terminal tabs too. They ask you first before they zip or unpack files on S3
  or make a presigned link, as they do before they copy or delete. **`AirSCP --agent … --out -`** writes a screenshot to
  standard output.
- **Security**: Remote Desktop now uses FreeRDP 3.32.2, which fixes 40 problems found in 3.32.1 (10 of them rated
  high). None has a CVE number yet; they are listed in
  [FreeRDP's security advisories](https://github.com/FreeRDP/FreeRDP/security/advisories).

## AirSCP 1.2.0

- **AI agents ask before they change things**: before an agent deletes, copies or runs something, types into a
  Terminal tab or works on a Windows desktop, a small window asks you: **Deny**, **Allow Once** or **Allow for 15
  Minutes**. Turn it off in **Settings ▸ Ask before agents change things**. See
  [Allow or deny what an agent changes](https://kleash.github.io/airscp/ai-agents.html#allow-or-deny-what-an-agent-changes).
- **More in Shortcuts, Siri and Spotlight**: **Upload Files**, **Download Files**, **Find Files**, **Run Snippet**,
  **Start Tunnel**, **Stop Tunnel** and **Open Favourite Folder**. Spotlight (macOS 15 and later) finds your saved hosts
  and Remote Desktops by name. See [Shortcuts, Siri & Apple Intelligence](https://kleash.github.io/airscp/shortcuts-and-ai.html).
- **Ask AirSCP does things**: describe it (“upload ~/Sites/site to web-01, leave out node_modules”), click **Do It…**,
  read the steps, then click **Run**. Nothing runs before that, and AirSCP still asks before it replaces anything.
- **Explain, Summarize and Suggest**: **Explain…** in Monitor and in Snippets, **Summarize…** in the Command Log, and
  **Suggest…** next to Other ssh options, Leave out, Find Files' pattern and permissions. All on this Mac.
- **Select by pattern**: **Edit ▸ Select by Pattern…** (<kbd>⌘+</kbd>), Deselect by Pattern, Select Same Kind and
  Invert Selection. **File ▸ Compare Folders** marks what differs between this Mac's folder and the server's. See
  [Select by pattern, compare folders, move, link](https://kleash.github.io/airscp/files/select-and-compare.html).
- **Move, copy and link on a server**: **File ▸ Move To…**, **Copy To…** and **New Symbolic Link…**; **Copy Names**;
  **Go ▸ Other Pane's Folder**.
- **Move between this Mac and a server**: **Upload and Delete…**, **Download and Delete…**, or hold <kbd>⌘</kbd> while
  you drag. Originals go only after their copy is done (and its checksum matches, when transfers are verified).
- **Replace If Newer** when a file already exists: only newer files are copied.
- **The Transfers list**: **Move Up** and **Move Down** for waiting transfers, and **When Done**: disconnect, sleep this
  Mac or a notification once everything has finished.
- **Owner, group and checksums**: Permissions… changes the owner and group; Get Info works out a file's SHA-256 (or SHA-1,
  MD5) and compares it with one you paste.
- **Snippets on selected files**: `{file}`, `{files}`, `{name}` and `{folder}` in a snippet, then right-click ▸ **Run
  Snippet**. See [Save commands as snippets](https://kleash.github.io/airscp/commands/snippets.html).
- **Synchronize options**: compare by size and date, size only, date only or contents (SHA-256); only files on both
  sides; also replace newer files; and **Reverse** one file. See [Synchronize](https://kleash.github.io/airscp/synchronize.html).
- **Favourites remember this Mac's folder too**, when the other pane shows one.
- **The editor** has a find bar (<kbd>⌘F</kbd>), **Go to Line…** (<kbd>⌘L</kbd>) and **Revert to Server Version**.
- **Find Files' results**: select several, then **Download…**, **Delete…** or **Copy Paths**.
- **The Terminal tab knows your commands** (bash and zsh): each one shows how it ended and how long it took;
  right-click it for **Copy Output**, **Copy Command** and **Run Again**; <kbd>⌘↑</kbd> and <kbd>⌘↓</kbd> jump between
  them. <kbd>⌘F</kbd> finds text, **Follow in Files** keeps the server pane in the shell's folder, **Insert Snippet**
  types a snippet at the prompt, and a setting sends **Open Terminal Here** to the tab. See
  [The Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html).
- **Server Info, Change Password, links**: **Host ▸ Server Info…** shows the server's key fingerprint, software,
  encryption and free space; **Host ▸ Change Password…** runs `passwd` in the Terminal tab; `sftp://` and `ssh://` links
  open in AirSCP, and **Host ▸ Copy Link** makes one. See [Server information](https://kleash.github.io/airscp/connecting/server-info.html).
- **Browse and copy as root**: **Host ▸ Edit… ▸ Advanced ▸ Browse and transfer as**, with sudo that needs no password.
  See [Browse and copy files as root](https://kleash.github.io/airscp/connecting/browse-as-root.html).
- **Proxies**: SOCKS5 proxies; HTTP proxies that ask for a Digest login; and Import from WinSCP keeps a site's proxy
  when you already have its bastion.
- **Certificate Manager**: **New…** makes a key with a certificate request (CSR) or a self-signed certificate;
  **JKS…** and **Truststore…** write Java keystores and truststores (PKCS#12 or JKS); **Verify…** checks a
  certificate's chain against a CA bundle or the authorities this Mac trusts, for a host name too. See
  [Create a certificate or request](https://kleash.github.io/airscp/certificates/create.html).
- **Fixed**: on accounts that allow only sftp, a path longer than sftp takes on one line (about 2,000 bytes) is
  refused with a message: a server with such deep folders could otherwise have had sftp run the rest of the path as a
  command on this Mac.
- **Fixed**: Get Transfer Status said nothing once every transfer had finished.
- **Fixed**: PKCS#12 files made with **Compatible with older systems** had no password check (MAC), which older
  systems expect.

## AirSCP 1.1.0

- **Shortcuts, Siri and Apple Intelligence**: AirSCP's actions (Connect to Host, Open a Shell, Open Remote Desktop,
  Disconnect All, Transfer Status) are in Shortcuts and Spotlight. On a Mac with Apple Intelligence, **Help ▸ Ask
  AirSCP…** answers questions on this Mac, and a failed connection has **Explain…**. See
  [Shortcuts, Siri & Apple Intelligence](https://kleash.github.io/airscp/shortcuts-and-ai.html).
- **Certificate Manager**: **Tools ▸ Certificate Manager…** opens certificates, keys, chains, PKCS#12 files and Java
  keystores, shows their details and expiry, and saves them as PEM, DER, chains, keys or PKCS#12, each with the
  `openssl` command that does the same. **Tools ▸ View Server Certificate…** shows what a TLS server sends. See
  [Certificates and keystores](https://kleash.github.io/airscp/certificates/).
- **A terminal inside AirSCP**: each host has a **Terminal** tab (**Host ▸ Terminal Tab**, <kbd>⌃⌘T</kbd>) with a
  shell on the server, through the same connection. Right-click a file name in its output to show it in Files,
  download it, edit it or copy its path; drop Finder files on it to upload them where you are. See
  [The Terminal tab](https://kleash.github.io/airscp/commands/terminal-tab.html).
- **Import your sites from WinSCP**: **File ▸ Import from WinSCP…** reads the WinSCP.ini that WinSCP exports and makes
  hosts with their groups, keys (.ppk files), tunnels and HTTP proxies. Saved passwords stay behind. See
  [Import your sites from WinSCP](https://kleash.github.io/airscp/connecting/import-from-winscp.html).
- **AI agents click the right spot on a Windows desktop**: they click in the pixels of the desktop picture AirSCP
  gives them, see a close-up of each click, and can press the Windows key (<kbd>⊞</kbd> <kbd>E</kbd>,
  <kbd>⊞</kbd> <kbd>R</kbd>). Their guide tells them to use the keyboard first.
- **See which ports a server listens on**: **Monitor ▸ Ports** lists them with the program, its user and how many
  connections each has, and shows who is connected to the one you pick, from which addresses. Kill the program, or
  show it among the processes. AirSCP reads the ports only while you look at them.
- **Tunnels say where they lead**: **Add Tunnel…** reads as a sentence (open port 8080 on this Mac, through your
  server, to the server itself, port 80), and the whole route shows as you type and in the list. The second port is
  the same as the first until you change it.
- **AI agents go through folders without clicking**: they go to a folder by its path and open a file or folder by its
  name, and get the folder's list back at once. You still see each step in the window.
- **Synchronize** leaves out what matches the server's **Leave out** patterns (the same list as for folder
  transfers, shown and changed in the sheet), and you can untick items in the list before you click **Synchronize**.
- **The editor never overwrites someone else's changes unasked**: when a file changed on the server after you opened
  it, **Save** asks first and can show you the server's version.
- **Owner and Group show names** on servers, as **Get Info** does. Point at one to see its number.
- **Pause and resume transfers**: one at a time from the Transfers list (right-click), or all at once with **Pause All**
  and **Resume All**. A single file continues where it stopped. See [Pause and resume transfers](https://kleash.github.io/airscp/transfers/pause-and-resume.html).
- **Check copies with SHA-256**: **Verify with Checksum** compares a copied file with the original, and **Settings ▸
  Verify transfers with SHA-256** checks every file as it arrives. A damaged copy shows **Mismatch**, and **Retry**
  copies it again. See [Check a copy with its checksum](https://kleash.github.io/airscp/transfers/verify-checksums.html).
- The toolbar's **+** lists **New Host…** first. Before, it showed only **New Remote Desktop…** and **New Group…**.
- In the New Host and Remote Desktop sheets, the blue ring around the field you type in fits the field.
- After **Disconnect**, the server's pane no longer shows files that may be out of date. It says it is disconnected,
  and **Reconnect** shows the same folder again.
- The horizontal scroll bar no longer covers the last file in a long folder.
- **Debug logging on**, at the bottom of the sidebar, has a **Turn Off** button. **Help ▸ Turn On Debug Logging**
  (**Turn Off Debug Logging** while it is on) switches it too.
- **Remote Desktop full screen shows the way out**: a note says <kbd>⌃⌘F</kbd> leaves it, and the menu bar comes
  down at the top of the screen with **View ▸ Exit Full Screen**.
- **The shared folder explains itself**: the bar says how to open `\\tsclient\AirSCP` in Windows, with a button that
  copies the path. When Windows' policy blocks shared folders (Explorer shows an empty **tsclient**), the bar says so,
  and to copy and paste files instead.

- Smaller things: in dark mode a Blue tag no longer looks like an untagged host; the host's route has a line of its
  own above the tabs; in light mode the server figures above the tabs show their units, totals and free space; a host
  whose Other options connect through ProxyCommand or ProxyJump shows that route in the sidebar; **Copy ssh Command**
  works for hosts behind an HTTP proxy without a login; AI agents see every alias of **Import from ~/.ssh/config**,
  however many there are; AirSCP clears the temporary folders a stopped copy of it left behind.

## AirSCP 1.0

The first release.

(Picture: AirSCP 1.0: hosts, two file panes and transfers in one window)

- **One window for all your servers**: saved hosts in groups, connected ones at the top, <kbd>⌘1</kbd> to
  <kbd>⌘9</kbd> to switch.
- **Two-pane file browser**: drag to copy between your Mac and a server, or between two servers.
- **Background transfer queue** with resume after a lost connection and a speed limit.
- **Folders as one stream**, with **Compress during transfer** and **Leave out** patterns.
- **Synchronize** two folders, with a preview before anything is copied.
- **Find Files** on a server, by name or pattern.
- **Server file commands**: edit, permissions, compress, extract, run, Get Info.
- **Jump hosts and HTTP proxies**, with the route shown in the sidebar.
- **Remote Desktop for Windows**, built in, with the clipboard and files both ways.
- **Linux monitor**: CPU, memory, disks and processes, with Kill.
- **Tunnels**: local, remote and SOCKS.
- **Keys**: make key pairs of every common type, install them on servers, import PuTTY keys and export them for
  PuTTY 0.75 and later.
- **Trust choices** for self-signed certificates and company certificate authorities.
- **AI agents** can drive AirSCP over MCP when you allow it.
- **Two looks**: Paper in light mode and Night Harbor in dark mode, with a CPU, memory and disk strip for a connected
  Linux server.
- **Help everywhere**: tooltips on every control, a welcome sheet, AirSCP Tips, and this help with a **?** button on
  every sheet with choices.
- **Debug logs** that show each step of a failed connection, to attach to a problem report.


---

Source: https://github.com/kleash/airscp/blob/main/Resources/AgentGuide.md

# AirSCP agent guide

AirSCP is a Mac app for SSH servers (saved hosts, a two-pane file browser with Find Files and Synchronize, transfers,
remote file operations, a Linux monitor, tunnels, HTTP proxies and jump hosts), S3 storage and Windows desktops (a
built-in Remote Desktop client). These tools drive the running AirSCP the way its user does. `guide topic=<name>` gives
the details: tools, hosts, proxies, transfers, files, monitor, tunnels, keys, settings, rdp, troubleshooting.

## overview
How to work with AirSCP:
- Loop: `snapshot` → one action (`menu`, `press`, `set`, `select`, `go`, `drop`, …) → `wait` for its effect →
  `snapshot` again. Never sleep: `wait` polls (until connected, disconnected, sheet, no_sheet, listed, transfers_done,
  rdp_connected, rdp_drawn, text, monitor, found, compared) and stops early, with the question, when a sheet appears.
- Every action returns `{ok, sheet, banner}`: a sheet in the reply is a question AirSCP is asking. Answer it before
  anything else: `set` its fields, then `press` a button (OK, Trust, Upload, Replace, Delete…). Confirmations stay in
  the way on purpose: Delete asks, and you press "Delete".
- Menus: `menu path="Host > Connect"`, `menu path="File > New Folder…"` (… may be left out). A disabled item is
  refused with the reason (e.g. "This account allows file transfers (sftp) only."). `snapshot include=["menus"]`
  lists every item, enabled or not, with its shortcut and reason.
- Files: `go path=/var/log` shows a server folder (`pane=left`: this Mac) and answers with its rows once listed; `open
  name=logs` opens a row as a double-click does (`..` goes up). File commands act on the focused pane's selected rows:
  `select pane=right names=["a.txt"]`, then `menu path="File > Rename…"` or `menu path="context > Rename…"`.
- Controls are found by accessibility id (e.g. `hostEditor.hostname`, `right.filter`, `prompt.answer`), by their
  label or title ("Address", "Password", "Remember in Keychain"), or by placeholder. `snapshot include=["sheets"]`
  shows a sheet's fields and buttons; `include=["elements"]` lists every control of the window, the rows of short lists
  too, with its id, frame and help (its tooltip: what it does, or while it is off, why).
- Other windows (Settings, Keys, Snippets, file editors): add `in="window:<title>"` to `press`, `set`, `select`,
  `menu`, `key`, `type`, `click` and `snapshot` (its elements). Without it, menus and keys act on the main window.
- Hosts and desktops are chosen in the sidebar: `select pane=sidebar names=["web"]`, then `menu path="Host > Connect"`.
  Never click in the file panes or the sidebar (`go`, `open`, `select`, `menu` take them by name). `screenshot` only to
  see how something looks (it is large; the snapshot has the facts).
- A Windows desktop (Remote Desktop) is driven by keys first: `key target=rdp` "win+e" (File Explorer), "alt+d" (its
  address bar: `type target=rdp` a path such as D:\Data, then "return"), "win+r" (Run). Click only where no key does
  it: `click target=rdp` takes pixels of `screenshot target=rdp` as they are. More: `guide topic=rdp`.
- Secrets never come back: password fields read as "•••(n)", and no tool reads the Keychain. From a shell, give a
  password with `value=-` and the password on standard input: a command line can be read by every process.
- Open and Save panels (Upload…, Download To…, Import Hosts…, Export Hosts…, Choose a Key File…, Other Key File…,
  Choose…, Send Files…, Paste Items to Mac…) can't be driven: give the command that opens one `file=<path>` (or
  `files=[…]`), which is chosen instead, e.g. `menu path="File > Export Hosts…" file=/tmp/hosts.json`; the reply's
  `panelFolder` is where the panel would have opened (one that opened anyway: `press title=Cancel`). Quick Look is
  refused. Commands that hand over to another app (Terminal, Finder, the default app, the clipboard) run, unseen.
- Agent control is off unless the user turned it on (AirSCP ▸ Settings ▸ "Allow AI agents to control AirSCP (MCP)");
  the sidebar then shows the user your name, your actions and a way to turn it off. `snapshot` → agent: client, actions.
- Changes wait for the person at the Mac (Settings ▸ "Ask before agents change things"; `snapshot` → agent.asksFirst):
  deleting, replacing, renaming, copying or opening files, permissions, keys for a server or the ssh agent, tunnels,
  commands, kills, disconnecting, quitting, typing into a terminal or Windows desktop. "The person at the Mac declined"
  or "didn't answer": nothing was done; don't try another way, tell the user (guide topic troubleshooting).
- A first run with no hosts shows the "Welcome to AirSCP" sheet: press Start first. The Help menu's AirSCP Help items
  and a sheet's "?" button (id `help`) open the browser, outside AirSCP; Tips and Agent Guide open short texts.

## tools
Each tool takes a JSON object. From a shell: `AirSCP --agent <tool> key=value …` (values are text, except for
arguments the tool takes as numbers, true/false or lists: `timeout=60`, `names=["a.txt"]`), `--json` for the raw
reply, `--out shot.png` for an image (`--out -` writes it to standard output). The binary is `/Applications/AirSCP.app/Contents/MacOS/AirSCP` (in `~/Applications` when
AirSCP was installed with `./install.sh`).

- `snapshot {include?, rows?, log?, in?}` — AirSCP's state. Default sections: windows, selection, sidebar, workspace
  (host, tab, banner, shell, tunnels), panes (left/right: source, dir, rows, selected, sort, filter, status, busy,
  hiddenColumns, favourites), transfers (summary, speedLimit, jobs with their ids), rdp, sheets, and while their sheet
  is open find (Find Files' results), sync (Synchronize's plan) and configImport (Import from ~/.ssh/config's
  aliases); always debugLog (on, path: the debug log's file, see troubleshooting). Add "log" (command log), "monitor" (connected, the figures, and the processes as the table
  lists them: its search, sort and selection; the ports while Monitor ▸ Ports is shown), "menus", "elements",
  "settings"; `in="window:Keys"` makes "elements" that window's. Example: `snapshot {"include": ["panes", "transfers"], "rows": 50}`.
- `screenshot {target?, scale?}` — a PNG drawn by AirSCP: target "main" (default; sheets and panels composited),
  "sheet", "rdp" (the Windows desktop alone, at its own pixel size, which the reply gives: `click target=rdp` takes
  its pixels as they are), "window:Settings", "element:right.table"; scale 1 or 2. Example: `screenshot {"target":
  "rdp"}`.
- `menu {path, pane?, in?, file?, files?}` — a menu-bar command, or `context > <entry>` from a context menu: a file
  pane's (its selected rows) or with `pane: "transfers"` the Transfers panel's (its selected jobs: Cancel, Retry,
  Remove, Show Details…, Show in Finder). `in`: the window whose command it is, as if it were in front. `file`/`files`:
  what the Open or Save panel it opens chooses. Example: `menu {"path": "View > Show Hidden Files"}`; an editor's
  `menu {"path": "File > Close", "in": "window:notes.txt"}`.
- `press {id | title, in?, file?, files?}` — a button, checkbox, switch, tab or segment, in the frontmost sheet first
  (a window a sheet covers isn't reached: answer the sheet first). `in`: "sheet" or "window:<title>". A disabled
  button is refused with its reason when it has one. A control a long form has scrolled away is scrolled into view
  first (so is `set`'s), as a person scrolls to it. Example: `press {"title": "Trust"}`; tabs: `press {"title":
  "Monitor"}`.
- `set {id | title, value, in?, file?}` — a text or password field, a checkbox or switch (true/false), a pop-up menu
  or segmented control (by the option's title, or words of it: "zip" is "ZIP archive (.zip)"). Text is set as it is
  (no smart quotes). A pane's filter replies with the filtered rows. Synchronize's list: a row's box by the item's path
  as title. Example: `set {"id": "hostEditor.login", "value": "id_lab"}`.
- `key {combo, target?, in?}` — keys as events: "cmd+shift+n", "return", "escape", "down", "f5", "cmd+delete",
  "capslock". "delete" is the Mac's ⌫ (Backspace); "forwarddelete" is the Delete key (⌦, Windows' Del: in Explorer
  "delete" goes up a folder, "forwarddelete" deletes). They go to the frontmost sheet, else the main window (or the
  window `in` names); target "rdp" sends them to the Windows desktop, where "win" is the Windows key ("win+e",
  "win+r"; "win" alone opens Start) and "ctrl", "alt" and "shift" are Windows' own ("cmd" is Ctrl). Example:
  `key {"combo": "win+e", "target": "rdp"}`.
- `type {text, target?, in?}` — text into the focused field, or the Windows desktop with target "rdp" (key by key,
  there at a person's pace, about ten keys a second, which Windows 11's apps keep up with; more than 1 000 characters
  key by key are refused outside a text field: use `set`). Example: `type {"text": "notepad", "target": "rdp"}`.
- `click {x, y, target?, button?, count?, modifiers?, wheel?, in?}` — a click at window points (count 2:
  double-click). Refused in the file panes and the sidebar (`go`, `open`, `select` and `menu` take folders, rows and
  hosts by name); elsewhere the last resort after `press` and `set`. With target "rdp", x, y are pixels of the Windows
  desktop's picture (`screenshot target=rdp`) from its top left, as they are (the window's size, Retina and full
  screen change nothing), and the reply has a picture of the spot, zoomed 2×, with a red cross where it clicked.
  Right-clicks only on the Windows desktop (elsewhere use `menu context > …`). On the Windows desktop the pointer rests
  there a moment first (for controls that react to it), and `wheel` turns the mouse wheel there instead (notches; up
  when positive). Example: `click {"x": 600, "y": 400, "count": 2}`, `click {"target": "rdp", "x": 912, "y": 858}`.
- `focus {pane | target}` — pane "left"/"right" (menu commands then act on it), or target "sidebar", "filter",
  "path" (the Go to Folder field), "desktop". Example: `focus {"target": "filter", "pane": "right"}` then `type`.
- `go {path, pane?}` — shows a folder in a file pane, as Go to Folder (⇧⌘G) does: an absolute path, `~` or `~/…` (the
  pane's home), or relative to the folder shown (`..` goes up). pane "right" (default: the host's server) or "left"
  (this Mac, or the server its source menu shows). It waits until the folder is listed, gives the pane the focus (File
  menu commands then act on it) and answers with the pane: dir, total, rows (name, kind, size, modified, perm, owner,
  group; hidden files only while View > Show Hidden Files is on) — the first 100, `more` counts the others (`snapshot
  rows=…` lists them). A folder it can't show is an error: "No such folder: …", "Permission denied: …", "… isn't
  connected". Example: `go {"path": "/var/log"}`, `go {"pane": "left", "path": "~/Downloads"}`.
- `open {name, pane?}` — opens a file pane's row by its name, as a double-click (or Return) does: a folder, or a link to
  one, is shown in the pane and answered as `go` answers; ".." is the enclosing folder; a file opens in its app on this
  Mac (outside AirSCP: you can't see it; download a file to read it). Example: `open {"name": "reports"}`.
- `select {pane | in, names | ids | all | none}` — rows: pane "left"/"right" (file names, byte for byte: "café" in
  its two Unicode forms are two names), "sidebar" (names: one host or desktop), "processes" (a process name, PID or part
  of its command, among those the Monitor lists with its search), "ports" (one port of Monitor ▸ Ports: its number,
  address:port or process name), "transfers" (a job's name, or `ids` from snapshot); with `in` instead of pane, a list
  in that window or sheet (keys, snippets, the Proxies sheet, Find Files' results; Synchronize's list: the items
  ticked, by path).
  Example: `select {"pane": "right", "names": ["a.txt", "b"]}`, `select {"in": "window:Keys", "names": ["id_lab"]}`.
- `sort {pane, column, ascending?}` — a file pane: name, size, modified, permissions, owner, group, kind; pane
  "processes": pid, user, cpu, mem (% of RAM), memory (its size: RSS), time (running time), state, command. Example:
  `sort {"pane": "right", "column": "size", "ascending": false}`.
- `drop {files, pane | target}` or `{from, to, into?, move?}` — what a drag does. Mac files onto a server pane
  (upload), `target: "desktop"` (the Remote Desktop's shared folder) or `target: "keys"` (a PuTTY .ppk on the open
  Keys window: Import Key opens for it); the selected rows `from` a pane `to` the other
  (`move: true` moves within one server), to `"local:/Users/me/Downloads"` (Download To…: with its questions), or to
  `"finder:/Users/me/Downloads"` (a drag into a Finder window: no questions, a taken name gets a number). Questions
  come as sheets. Example: `drop {"files": ["/tmp/site"], "pane": "right"}`.
- `wait {until, host?, pane?, path?, text?, timeout?}` — until "connected" / "disconnected" (host, default the selected
  one), "sheet" (optional text its title, text, buttons or field names must contain: not what its fields hold),
  "no_sheet", "listed" (pane done listing and filtering; optional path, or text = a row name), "transfers_done",
  "rdp_connected", "rdp_drawn" (the desktop shows a picture, not the blank frame Windows starts with), "text" (anywhere
  in the snapshot, incl. monitor and log, and in AirSCP's other windows), "monitor" (the Monitor has read the server;
  with text, it lists a process with that in its name or command; showing Ports, the ports and the picked port's
  connections are read, and text is in a port's row or a connection; it fails at once with the Monitor's failure, e.g.
  on an sftp-only account), "found" (Find Files' search ended: its results), "compared" (Synchronize's comparison ended:
  its plan). Timeout 30 s by default; a wait ends when the agent that asked has gone. Example: `wait {"until":
  "connected", "host": "chain target"}`.
- `guide {topic?}` — this guide.

## hosts
- Facts about a connected host: `menu path="Host > Server Info…"` (a sheet: key fingerprint, software, cipher, what it
  can do, free space; Copy, Done). `menu path="Host > Copy Link"` puts an sftp:// link on the clipboard. `menu
  path="Host > Change Password…"` runs passwd in the Terminal tab for the user to answer: never type a password there
  unasked.
- New host: `menu path="File > New Host…"` → a sheet. Fields: `hostEditor.name`, `hostEditor.hostname` (Address),
  `hostEditor.port`, `hostEditor.username` (User name), `hostEditor.login` (pop-up: "Keys in ~/.ssh and the ssh agent
  (default)", the keys of ~/.ssh as "id_ed25519 · ED25519 · me@mac", "Password", or a key elsewhere: `set
  id=hostEditor.login value="Choose a Key File…" file=/path/to/key` (a PuTTY .ppk opens Import Key on the editor: see
  keys); "Generate New Key…" opens New Key Pair on the editor, whose result has "Install on This Host" (logs in as
  typed, adds the key, and Log in with then uses it; the result shows next to Test Connection) and "Use for This
  Host"), `hostEditor.password` (only with Password),
  `hostEditor.jump` ("Connect through": another host's name), `hostEditor.remoteFolder` (Start in folder),
  `hostEditor.group`. Under Advanced (`press title=Advanced` shows them; an edited host that uses one shows them
  already): `hostEditor.proxy` (Proxy; its "Add Proxy…" opens the proxy editor on the host editor),
  `hostEditor.keepAlive`, `hostEditor.autoReconnect`, `hostEditor.forwardAgent` ("Let the server use my ssh agent"),
  `hostEditor.hostKey` (Server key: "Ask (default)", "Trust new servers automatically" (accept-new: a changed key is
  still refused), "Don't check (insecure)"; Other options can't set StrictHostKeyChecking),
  `hostEditor.options` (Other ssh options, one per line; `set id=hostEditor.addOption value=Compression` adds a common
  one). Each options line is checked with `ssh -G` as it is typed: a bad one is named, with ssh's reason, in the
  sheet's text (and Add is off). `press title=Add` (Save when editing; disabled while the sheet's text names a
  problem). `press title="Test Connection"` logs in and out with the fields as typed: its questions come as sheets on
  the editor, and the result is in the editor's text (`wait until=sheet text="Logged in"`).
- S3 storage (Amazon S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi, Ceph): `menu path="File > New S3 Connection…"` →
  a sheet. Fields: `s3Editor.name`, `s3Editor.endpoint` (empty: Amazon S3), `s3Editor.region`, `s3Editor.accessKey`,
  `s3Editor.secret` (from a shell: `value=-`), `s3Editor.bucket` (the bucket to open at; needed for a key that may not
  list the buckets), `s3Editor.group`; under Advanced (`press id=s3Editor.advanced`): `s3Editor.pathStyle`,
  `s3Editor.token`, `s3Editor.proxy`. `press id=s3Editor.test` checks the keys (its result is in the sheet's text:
  "Connected: 3 buckets."), `press id=s3Editor.save`. `menu path="File > Import from ~/.aws…"` makes connections from
  the AWS CLI's profiles (its sheet names the profiles left out, with why). In the sidebar such an entry has
  `"kind": "s3"`; it connects and disconnects as a host does, with the Files tab only: Terminal, Monitor, Tunnels, Run
  Command, Server Info and Copy ssh Command are refused with the reason. `menu path="Host > Copy Link"` copies its
  s3://bucket/folder/ link.
- A host's route: `snapshot` → sidebar hosts' `route` ("via bastion", "via proxy corp-proxy", "via corp-proxy →
  bastion"; a jump host or proxy that no longer exists: "via a missing jump host" with a `warning`). The window's
  subtitle shows it too ("Connected · via bastion"), and the sidebar's search finds hosts by it.
- Every sidebar host has `hostKeyCheck` (ask, acceptNew, off) and every desktop `certificateCheck` (ask, trustNew,
  off, companyCA, with `caFile`); one whose checks are off has `shield` (the orange shield's tooltip), and its banner
  says so while connected.
- Edit, duplicate, delete: select it (`select pane=sidebar names=["web"]`) → `menu path="Host > Edit…"`,
  `"Host > Duplicate"`, `"Host > Delete…"` (asks), colour: `menu path="Host > Colour Tag > Red"`. Groups:
  `menu path="File > New Group…"` (`set id=prompt.name value=<name>`, press Create; a name in use is refused); a
  host's group is `hostEditor.group`; rename or delete one by its name: `menu path='Host > Rename Group > Lab'` (the
  name sheet, press Rename), `menu path='Host > Delete Group > Lab'` (asks; its hosts stay).
- Connect: `menu path="Host > Connect"`. Questions arrive as sheets on the window: a new server key ("Trust …?",
  press Trust), a password ("Password for web": `set id=prompt.answer value=…`, optionally `press title="Remember in
  Keychain"`, `press title=OK`), a key's passphrase, a verification code ("<host> asks": ssh's question is the label of
  `prompt.answer`; set it and press OK). A question asked again begins "That password wasn't accepted" (a code:
  "That answer wasn't accepted"). Then `wait until=connected`.
  Disconnect: `menu path="Host > Disconnect"`. A lost connection reconnects by itself when it can (banner
  "Reconnecting…"); `snapshot` → workspace.banner says what happened, with its buttons ("Reconnect"). Once
  disconnected, the server pane has no rows (its dir stays) and isn't "listed"; `press id=right.reconnect` connects
  and lists that folder again (`wait until=listed pane=right`).
- Import from ~/.ssh/config: `menu path="File > Import from ~/.ssh/config…"` → a sheet with a checkbox per alias;
  `snapshot` → configImport: every alias (chosen, added, refused, resolved), however many. `set title=<alias>
  value=false` leaves one out, `select in=sheet names=[…]` chooses only those (`all`, `none`) → `press title=Import`.
  Hosts to and from a file: `menu path="File > Export Hosts…" file=/tmp/hosts.json`,
  `menu path="File > Import Hosts…" file=/tmp/hosts.json` (the reply's sheet says how many were imported).
  WinSCP's sites: `menu path="File > Import from WinSCP…" file=/path/WinSCP.ini` (its .ppk keys beside it; the
  reply's sheet says how many hosts were made and what was left out).
- Terminal tab (a shell inside AirSCP, riding the connection): `menu path="Host > Terminal Tab"`, then
  `type target=terminal text="ls -la\n"` (a line break is Return) and `key target=terminal combo=ctrl+c`; `snapshot` →
  terminal: running, lines (the last `rows`, scrollback included), cursor, fullScreen, directory/title when the shell
  says them. `wait until=text text=…` waits for output while the tab is shown. After `exit`, `key
  target=terminal combo=return` starts a new shell. Prefer `go`/`open`/menus for files; the terminal is for commands.
  With bash and zsh the shell marks its commands: the terminal section then has `atPrompt` (true: the shell waits at an
  empty prompt, so a command typed now runs in it) and `commands`, the last 20: each one's `command` line, `status`
  (exit status), `seconds`, `output` (its last 50 lines) and `running`. Read a command's result there, not from
  `lines`: type it, then snapshot until its entry has a status. Other shells (BusyBox sh, fish) have neither. The tab's
  bar: `set id=terminal.follow value=true` (Follow in Files: the server pane follows the shell's folder), `set
  id=terminal.snippets value=<snippet name>` (typed at the prompt, not run; as any text for the terminal, it waits for
  the person at the Mac), `press id=terminal.find` then `set id=terminal.findText value=<text>` (find;
  `terminal.findCount` reads "2 of 5" in `snapshot include=["elements"]`), `press id=terminal.findDone`. Settings'
  `settings.openTerminalHereInTab` sends Open Terminal Here and Run in Terminal to this tab: the `cd` or the command typed
  at an empty prompt, else a new tab (nothing is typed into a busy shell).
  Tabs: each tab is its own shell on the same connection. `snapshot` → terminal: `tabs` lists them (`index` from 1,
  `title`, `directory`, `running`, `atPrompt` with bash and zsh, `shown`), `tab` is the index of the one shown, and the
  rest of the section (lines, commands) is that tab's; `type` and `key` with target terminal go to it. `press
  id=terminal.newTab` (or `menu path="Host > New Terminal Tab"`) opens one in the shown tab's folder; `set
  id=terminal.tabs value=2` shows tab 2 (by its index, or its title on the strip);
  `menu path="Host > Show Next Terminal Tab"` and `menu path="Host > Show Previous Terminal Tab"` go through them; `press
  id=terminal.closeTab` closes the tab shown (a sheet "Close this terminal tab?" first while a command runs; the last tab
  stays). History: `press id=terminal.history` → a sheet listing
  the host's commands, newest first; `set id=terminal.pickFilter value=<text>` filters it, `select in=sheet
  names=["<command>"]` chooses one, `press title=Insert` types it at the prompt without running it (as typing, it waits
  for the person at the Mac), `press id=terminal.clearHistory` forgets them. Insert Path: `press id=terminal.insertPath`
  → the same sheet with the names in the folder of the word before the cursor (relative to the shell's folder);
  `press title=Insert` types the name chosen in place of that word, quoted for the shell.
- Certificate Manager: `menu path="Tools > Certificate Manager…"` (its controls `in="window:Certificate Manager"`);
  open files with `press id=certificates.open files=[…]` (a password sheet: `set id=certificates.password`, `press
  title=Open`); `select in="window:Certificate Manager" names=["Certificate: web.example.com"]` (rows read "Certificate: …",
  "CA certificate: …", "Private key: RSA 2048"); `snapshot include=["elements"]` reads the details; buttons "Save PEM…",
  "Save DER…", "Save Chain…", "PKCS#12…" (`certificates.p12Name`, `certificates.p12Password`, then "Save…" with
  `file=`), "JKS…" (the same sheet: alias and password), "Save Key…" (`certificates.keyPassphrase`), "Public Key…", all
  taking `file=`. A server's chain: `menu path="Tools > View Server Certificate…"`, `set id=certificates.server
  value=host:port`, `press title=View`. A new key with a request or a self-signed certificate: `press
  id=certificates.new`, `set id=certificates.newKind value="Self-signed certificate"` (or "Certificate request (CSR)"),
  `certificates.commonName`, `certificates.names` (more host names and IPs, commas between), `certificates.organization`,
  `certificates.unit`, `certificates.locality`, `certificates.state`, `certificates.country`, `certificates.keyType`
  ("RSA 2048", "RSA 3072", "RSA 4096", "EC P-256", "EC P-384", "Ed25519"), `certificates.days`,
  `certificates.newPassphrase`, then `press title=Create… file=/path/web.crt` (a request: .csr; the key goes beside it as
  web.key; a file that exists is never replaced, and nothing is saved). With a certificate selected: "Truststore…" (tick
  or untick entries by their row titles with `press`, `certificates.trustFormat` "PKCS#12 (.p12)" or "Java keystore
  (.jks)", `certificates.trustPassword`, "Save…" with `file=`) and "Verify…" (`certificates.verifyAgainst` "Authorities
  this Mac trusts" or "A CA bundle file", then `press id=certificates.chooseBundle file=/path/ca.pem`;
  `certificates.verifyHost`; `press title=Verify`): the result is the line under the certificate's title and the status
  line (`snapshot include=["elements"]`).
- The same actions are reachable three ways: the menus (a person), these tools (you), and App Intents (Shortcuts, Siri,
  Spotlight: Connect to Host, Open a Shell on Host, Open Remote Desktop, Upload Files, Download Files, Find Files, Run
  Snippet, Start Tunnel, Stop Tunnel, Open Favourite Folder, Disconnect All, Get Transfer Status), all running the same
  code. Help >
  Ask AirSCP… (with Do It…, `ask.doIt`, `ask.plan`, `ask.run`), the Explain/Summarize buttons (`monitor.explain`,
  `log.summarize`, `snippet.explain`) and Suggest (`suggest.<field>`) are the user's own Apple Intelligence: don't use
  them for them.
- Terminal: `menu path="Host > Open Terminal"` opens Terminal.app, and "Copy ssh Command" fills the clipboard: their
  result is outside AirSCP. Run a command and read its output: `menu path="Host > Run Command…"` →
  `set id=runCommand.command value="uname -a"` (or a snippet: `set id=runCommand.snippet value=<its name>`) →
  `press title=Run` → `wait until=sheet text="Exit status"` (output, error output and "Exit status N" are in the
  sheet's text; a failure to run shows instead) → `press title=Close`. `press title=Stop` ends the command on the
  server too; what it printed so far stays in the sheet (the output shows while it runs).
- Snippets: `menu path="Window > Snippets"` (its controls `in="window:Snippets"`): `press id=snippets.add` makes
  one, or `select in="window:Snippets" names=["uptime"]` picks one; `set id=snippet.name value=…`, `set
  id=snippet.command value=…`, `set id=snippet.runInTerminal value=true`, `set id=snippet.host value=<host>`,
  `press title=Run`: the output comes in a Run Command sheet on the main window (in Terminal when "Run in Terminal" is
  on; refused while the main window shows a sheet). `press id=snippets.remove` deletes the selected one.
- Command log: `menu path="View > Show Command Log"`, and `snapshot include=["log"]`: every command AirSCP ran for
  the host, its exit status and error output.

## proxies
- A proxy is HTTP or SOCKS5: `set id=proxyEditor.kind value=SOCKS5` in New Proxy… (Digest logins are answered by
  themselves). Root's files: Host > Edit… > Advanced, `set id=hostEditor.sudoUser value=root` (needs NOPASSWD sudo on the
  server; connecting says why when it can't).
- Proxies: `menu path="Host > Proxies…"` → sheet → `press title="Add Proxy…"` → `proxyEditor.name`, `proxyEditor.host`,
  `proxyEditor.port`, `proxyEditor.username`, then `proxyEditor.password` (it appears once there is a user name) →
  `press title=Add` → `press title=Done` (or `key combo=escape`).
  The sheet's text lists the proxies; to change or remove one: `select in=sheet names=["Office"]` →
  `press title=Edit…` (its editor, press Save) or `press title=Remove…` (asks; a proxy hosts use can't go).
- A host behind a proxy: `press title=Advanced`, then `hostEditor.proxy` = the proxy's name. Through a bastion: make
  the bastion a host (with the proxy, if any), then the target's `hostEditor.jump` = the bastion (the target then uses
  the bastion's proxy).
  Connect asks the bastion's password (and the proxy's, unless saved): one sheet each, the title names whose.
- A proxy that refuses the password: the connect fails with "The proxy rejected the user name or password".

## transfers
- Move instead of copy: select items, then `menu path="File > Upload and Delete…"` (this Mac's pane) or `"File >
  Download and Delete…"` (a server's), `press title=Move`; originals go once each copy is done. Queued jobs: `menu
  path="context > Move Up" pane=transfers` / "Move Down". `set id=transfers.whenDone value="Notify"` (Do Nothing,
  Disconnect, Sleep This Mac, Notify) acts once when every transfer has finished: never choose Sleep This Mac unasked.
- Get Info: `set id=info.checksumAlgorithm value=SHA-256`, `press id=info.calculateChecksum`, read `info.checksum`; Permissions…
  also has `permissions.owner` and `permissions.group`.
- Upload: `drop files=["/path/a.txt", "/path/folder"] pane=right` (into the folder the right pane shows, or `into`).
  A folder (or 200+ items) asks first: "Upload … to “dev”?" with the checkbox "Compress during transfer — faster on
  slow links and for many small files" and the field
  `transfer.leaveOut` (names or patterns separated by commas, e.g. `set id=transfer.leaveOut value="*.log,
  node_modules, .git"`: left out at any depth; remembered for that server; a server without tar copies folders whole)
  → press Upload. A name that exists asks: Replace / Keep Both / Skip (checkbox "Do the same for the other N
  conflicts"); the sheet's text compares them: "New: 1.2 MB, 4 Oct 2026 at 15:21 · Existing: 1.1 MB, …".
- Download: `select pane=right names=["a.txt"]` → `drop from=right to=left` (into the local pane's folder) or
  `to="local:/Users/me/Downloads"`. As one archive: `menu path="File > Download as .tar.gz…"` (sheet: Download; its
  checkbox "Unpack it after the download (the archive is removed)").
  Folders download with the same sheet (Leave out, Compress).
- Speed limit for every host's transfers that start from then on: `set id=transfers.speedLimit value="5 MB/s"`
  (Unlimited, 1, 5, 10 or 50 MB/s); `snapshot` → transfers.speedLimit.
- Between two servers: show the other server in the left pane (its source menu: `set id=left.source value=<host>`),
  then `drop from=left to=right`.
- `wait until=transfers_done` (optionally host), then `snapshot include=["transfers"]`: each job's id, host, name,
  direction, size, percent, speed (or "stalled"), eta, status, problem, note. Cancel or retry: `select pane=transfers
  names=[<name>]` (or `ids=[<id>]`) → `press id=transfers.cancel` / `transfers.retry` / `transfers.remove`, or its
  context menu: `menu path="context > Show in Finder" pane=transfers` (a finished download), `"context > Show
  Details…"` (a problem's output); `press id=transfers.clearFinished`, `press id=transfers.cancelAll` (asks). The
  panel lists the queued, running and paused jobs first, then the newest 100 finished ones (newest first); snapshot has
  every unfinished job and the newest 500 finished ones of each host.
- Pause and resume: select the jobs (as above) → `menu path="context > Pause" pane=transfers` (queued or running ones)
  or `"context > Resume"` (paused ones); every job at once: `press id=transfers.pauseAll` / `transfers.resumeAll`. A
  paused job's status is "Paused" and its note says how it goes on: a single file keeps what it copied (`"resumable":
  true`) and continues where it stopped (then `"resumed": true`); folders, archives and server-to-server copies start
  again. Paused jobs wait through a lost connection and its reconnect (Resume is off while their host reconnects by
  itself); Cancel, Cancel All and Disconnect throw a paused job's part away. `wait until=transfers_done` doesn't wait
  for paused jobs.
- Check a copy against the original (SHA-256, single files): `menu path="context > Verify with Checksum"
  pane=transfers` on a finished job, or every file as it arrives with `set id=settings.verifyTransfers value=true
  in=window:Settings`. `wait until=transfers_done` waits for the checks too; then the status is "Verified" (with
  `sha256`), "Mismatch" (problem, and details with both checksums: `transfers.retry` copies the file again in place of
  the bad copy and checks it again) or "Not verified" (the note says why: an sftp-only account runs no checksum tool).
- A lost connection: a single file cut off keeps what arrived, and its job shows `"resumable": true` (problem "The
  connection to the server was lost."). Retry, or the automatic retry once the host has reconnected, continues it
  where it stopped (while the host reconnects by itself, transfers.retry is off: the job runs again by itself then): the job then shows `"resumed": true` and its percent goes on from there. Remove, Clear Finished,
  Cancel All and Disconnect throw the kept part away (an upload's on the server too). Folders, archives and
  server-to-server copies start again; a server-to-server copy that its source's lost connection stopped runs again
  once that host has reconnected by itself.
- Make two folders the same (one on this Mac, one on the server): Synchronize, in "files".
- Quitting while transfers run asks first ("Quit and cancel the transfers?"): the Quit reply carries that question.

## files
- The Files tab (`press title=Files`) has two panes: left = this Mac (or another connected server), right = the host.
  `snapshot` → panes.left/right: dir, rows, selected, status ("12 items, 2 selected — 30 GB available"). A row's owner
  and group are names, as Get Info shows them; ownerID and groupID are their numbers where the server tells them.
- Through folders without a click: connect (`select pane=sidebar names=["web"]` → `menu path="Host > Connect"` → `wait
  until=connected`) → `go path=/var/www` (the reply lists the folder; `open name=site` opens a row, `open name=..` goes
  up) → `select pane=right names=["index.html"]` → its command: `menu path="File > Download To…" file=/Users/me/Downloads`,
  `menu path="File > Upload…" files=["/Users/me/a.txt"]`, `menu path="File > Rename…"`, `menu path="context > Delete…"`.
- Also `menu path="Go > Back"`, `"Go > Enclosing Folder"`, `"Go > Home"`; this Mac's side: `go pane=left path=~/Downloads`.
- Find Files' results: `select in=sheet names=["a.log", "deep/b.log"]` (several, or `all: true`), then `press
  id=find.download file=<Mac folder>`, `press id=find.delete` (then Delete), or `press id=find.copyPaths`.
- Synchronize's options: `set id=sync.criterion value="Contents (SHA-256)"` (Size and date, Size only, Date only),
  `set id=sync.onlyBoth value=true`, `set id=sync.mirror value=true`. Editor: `press title="Go to Line…"` (`editor.line`),
  `press title="Revert to Server Version"`.
- Snippets with {file}, {files}, {name} or {folder} run on the selection: `select pane=right names=[…]`, then `menu
  path="context > Run Snippet > <snippet>" pane=right` (a Run Command sheet shows the output).
- Many at once: `menu path="Edit > Select by Pattern…"`, `set id=select.pattern value="*.log"`, `press title=Select`
  (Deselect by Pattern, Select Same Kind, Invert Selection likewise). `menu path="File > Move To…"` / `"File > Copy To…"`
  ask for a server folder (`set id=transfer.folder`, then Move or Copy); `menu path="File > New Symbolic Link…"` asks its
  name (`link.name`, Next) then its target (`link.target`, Create). `menu path="File > Compare Folders"` marks the rows
  that differ (snapshot rows carry `mark`, e.g. "Newer here").
- Favourites (a server's folders, kept per host): `focus pane=right` → `menu path="Go > Add to Favourites"` keeps the
  folder shown; `menu path='Go > Favourites > /var/log'` goes back to it, `menu path='Go > Favourites > Remove >
  /var/log'` drops it. `snapshot` → the pane's favourites (and `include=["menus"]` lists them).
- Filter: `set id=right.filter value=log` (the reply has the filtered rows). Hidden files:
  `menu path="View > Show Hidden Files"` (focused pane). Columns: `menu path="View > Columns > Owner"` shows or hides one (snapshot: the pane's
  hiddenColumns). Sizes of folders: `menu path="View > Calculate Folder Sizes"` (the files' sizes, as the status line
  adds them up; BusyBox servers: space on disk). Refresh: `menu path="View > Refresh"`.
- Server commands on the selected rows (File menu or `context > …`): New Folder… and New File… (a name sheet:
  `set id=prompt.name value=<name>`, press Create), Rename… (the same, press Rename), Duplicate, Delete… (or
  `key combo=cmd+delete`; asks: press Delete), Permissions… (`permissions.octal` or the rwx checkboxes, press Apply),
  Make Executable, Run… (`set id=run.arguments value=…`; press Run to see the output, or Run in Terminal), Compress…
  (`set id=compress.format value=zip` or `tar.gz`, press Compress), Extract Here / Extract to New Folder, Get Info
  (sheet with kind, size, dates, owner; press Done), Edit in AirSCP (an editor window titled "<file name> — <host>":
  `set id=editor.text value=… in="window:<file name>"` (a byte order mark the file starts with stays: JSON can't
  carry one), `press title=Save in="window:<file name>"` (when someone saved the file on the server after it was
  opened, Save asks first, a sheet on the editor: press Overwrite, Cancel, or Show Server Version, which opens their
  text read-only in a window titled "<file name> on the server — <host>": read it with
  `snapshot include=["elements"] in="window:<file name> on the server"`, then press Save again to overwrite it); read
  it with `snapshot include=["elements"] in="window:<file name>"`; close it with `menu path="File > Close"
  in="window:<file name>"`, which asks first when it has unsaved changes).
- Handed to other apps, so their result isn't visible here: Open (the default app), Show in Finder, Open Terminal
  Here (unless `settings.openTerminalHereInTab` is on: then the Terminal tab), Run in Terminal, Copy Path (the
  clipboard). Quick Look is refused: download the file and read it instead.
- Copy / cut / paste within a server: select → `menu path="Edit > Copy"` (or Cut) → select the target folder's pane
  → `menu path="Edit > Paste"`. Move by dropping: `drop from=right to=right into=/home/dev/dir move=true`. Replace
  keeps the old item until the copy is complete.
- Names and conflicts are checked against the server as it is now (an item made since the folder was listed is asked
  about, not replaced). Names are at most 255 bytes; Windows servers refuse device names (CON, NUL, …) too.
- Find Files (below the folder a server pane shows): `focus pane=right` → `menu path="File > Find Files…"` → `set
  id=find.pattern value="*.log"` (a name part, or a pattern with * ? [ ], any case) → `press title=Find` → `wait
  until=found`: status ("3 found."), count and results (paths below that folder; folders marked), also in `snapshot`
  → find. Go to one: `select in=sheet names=["logs/app.log"]` → `press title=Show` (the sheet closes and the pane
  shows its folder with it selected, its filter cleared if it hid it). Results show as they are found; `press
  title=Stop` stops a search and keeps them ("Stopped: 12 found so far."), `press title=Done` closes the sheet.
- Synchronize (one pane shows a folder on this Mac, the other a folder on the server: go to them as above):
  `focus pane=right` → `menu path="File > Synchronize…"` (the "Synchronize Folders" sheet; when either folder is a home
  folder or /, it waits for `press title=Compare`, as comparing can take minutes: see `started` in the snapshot's sync) →
  `wait until=compared`: sync with direction, delete, leaveOut, steps
  (action upload, download, trash = to the Trash on this Mac, delete = on the server; path below the two folders,
  size, replaces; `"ticked": false` when unticked), count, ticked (how many), summary ("The folders are the same."
  when nothing differs; the ticked ones counted with their sizes) and failure. Change the plan with
  `set id=sync.direction value="Both ways"` (or "This Mac → <host>", "<host> → This Mac") and `set id=sync.delete
  value=true` (one way only: delete what is only on the destination); `snapshot` shows the new steps. Leave out (the
  server's patterns, as in the folder-transfer sheet; remembered once you synchronize): `set id=sync.leaveOut
  value="*.log, node_modules"` → it compares again (`wait until=compared`); what matches isn't compared, copied or
  deleted, at any depth. Untick an item to leave it as it is: `set title="logs/app.log" value=false` (a row's box, by
  its path; true ticks it again); `select in=sheet names=["a.txt", "docs/"]` ticks only those, `select in=sheet
  all=true` / `none=true` every one or none (the sheet's Select All / Select None). `press title=Synchronize` queues
  the ticked copies (times kept; 20 or more files of one folder go as one stream) and runs the ticked deletions →
  `wait until=transfers_done`, then `wait until=listed` for each pane. `press title=Cancel` closes the sheet, also
  while it compares. A folder that can't be listed is named in the failure: add it to Leave out to compare without it.
- A command the server can't run (sftp-only account, no zip) is refused with the reason.
- S3 storage in a pane: "/" lists the buckets; `go path=/bucket/folder` (or `open name=bucket`) shows a folder.
  Uploads, downloads, drops, New Folder…, New File…, Rename…, Move To…, Copy To…, Delete…, Edit in AirSCP, Get Info
  (content type, storage class, ETag, SHA-256, metadata), Find Files… and Synchronize… (by size and date) work as on a
  server. `menu path="context > Download as .zip…"`, `menu path="File > Compress…"` (press Compress: a .zip next to
  the items) and Extract Here / Extract to New Folder are jobs in the Transfers list ("Zip on S3 storage…", "Extract on
  S3 storage…"); each waits for the person at the Mac first, as copies do. `menu path="context > Copy S3 Link"` copies
  s3://bucket/key; `menu path="context > Copy Presigned Link…"` waits for the person too (anyone with the link can
  download the file), then asks how long it works (`set id=presign.expiry value="For 1 day"`): press "Copy Link".
  Permissions, symbolic links, Run and the terminal are refused with the reason.

## monitor
- `press title=Monitor` (the host's tab) → `wait until=monitor` (or `wait until=monitor text=<a process name>`) →
  `snapshot include=["monitor"]`: connected, cpu, load, memory, swap, uptime, system, disks, and the processes as the
  table lists them (pid, user, cpu, memory as % of RAM, name, command, state; its search, sort and selection);
  `failure` says why there are no figures (an sftp-only account, a server that isn't Linux), `processNote` why there
  are no processes (no ps). It refreshes every 3 s while it is shown, also behind other windows while you are at work;
  disconnected, it shows nothing.
- Sort: `sort pane=processes column=pid` (user, cpu, mem: % of RAM, memory: RSS, time, state, command;
  `ascending=false`).
- Kill: `set id=monitor.search value=backup` (the list shows only those) → `select pane=processes names=["backup"]` →
  `press title=Kill` (or "Force Kill") → the confirmation → press the same title again. When the account may not, a
  sheet offers "Kill with sudo in Terminal" on a server that has sudo (it runs in Terminal: its result isn't visible
  here); without sudo, it says the process can't be killed from this account.
- Ports (what the server listens on, and who is connected): `press title=Ports` (`monitor.view`: Processes | Ports) →
  `wait until=monitor` (or `text=8080`: a port, process, address or remote address) → `snapshot include=["monitor"]`:
  `view` "Ports" and `ports`: `listening` as the table lists them (protocol, address, port, pids, process, command,
  user, connections: open TCP connections; UDP has none), `othersHidden` (some ports are other users' processes,
  which this account can't see: their pids are empty; root sees them), `note`, `paused`, `search`
  (`monitor.portSearch`). `select pane=ports names=["8080"]` picks a port (by number, address:port or process name)
  → `wait until=monitor` → `selected`, its `connections` (address, port, state; the first 2000) and `from` (how many
  from each address). With a port picked, `press title=Kill` / "Force Kill" (as above) and "Show Process" (Processes,
  with its PID searched for and selected). The ports are read only while Ports is shown: every 5 s, `press
  title=Pause` stops that, `press id=monitor.refresh` reads them now; `press title=Processes` goes back (`ports` is
  then left out of the snapshot).

## tunnels
- `press title=Tunnels` (tab) → `press title="Add Tunnel…"` → a sheet that reads as a sentence: `set
  id=tunnelEditor.type value=Local` (Remote, "SOCKS proxy"), `tunnelEditor.listenPort` (the port to open: on this Mac,
  for Remote on the server), `tunnelEditor.destination` ("The server itself" for Local, "This Mac" for Remote: ssh's
  localhost at that end; or "Another machine", which shows `tunnelEditor.targetHost`: a name that end looks up),
  `tunnelEditor.targetPort` (the port to open until you set it) → `press title=Save`. The sheet's text has the route it
  saves, and why Save is off.
- Each tunnel is named by its route, as its row shows it (web: the host's name): "localhost:8022 on this Mac → web →
  localhost:22 on web (the server itself)", "localhost:9000 on web → this Mac → localhost:3000 on this Mac",
  "localhost:1080 on this Mac (SOCKS proxy) → web → any address web can reach". Its switch is `press title=<route>` (or
  `set title=<route> value=true`), then `press title="Edit <route>"` (only while it is off) and `press title="Remove
  <route>"`. `snapshot` → workspace.tunnels: each one's title (its route) and whether it is on (screenshots may draw a
  switch off). This Mac's end listens on 127.0.0.1; a port another program listens on is refused, with its error
  under the row (elements).

## keys
- `menu path="Window > Keys"` opens the Keys window: use `in="window:Keys"` for its controls (and its sheets). The keys
  (name, type, comment, fingerprint): `snapshot include=["elements"] in="window:Keys"`. Select one first for its
  buttons: `select in="window:Keys" names=["id_lab"]` → `press title="Install on Host…" in="window:Keys"` (a sheet:
  Host pop-up → Install), `press title="Add to Agent" in="window:Keys"` (may ask the passphrase, which goes into the
  login Keychain), Copy Public Key (a menu: `set id=keys.copy value=OpenSSH in="window:Keys"` puts OpenSSH's line on
  the clipboard; "SSH2 (RFC 4716)" and "PEM (PKCS#8)" the other formats). A key outside the folder: `press
  title="Other Key File…" in="window:Keys" file=/path/to/key`.
- New Key Pair: `press title="New Key Pair…" in="window:Keys"` → a sheet: `newKey.type` ("Ed25519 (recommended)",
  "ECDSA 256/384/521", "RSA 2048/3072/4096"; no DSA), `newKey.name` (never an existing file), `newKey.comment`,
  `newKey.passphrase` and `newKey.confirm` (optional; they go to ssh-keygen through askpass, never into a command
  line), `newKey.remember`, `newKey.copy` (on: the public key goes on the clipboard), Change… (`press
  id=newKey.folder file=/folder`); under Advanced (`press id=newKey.advanced`): `newKey.format` (private key:
  "OpenSSH (default)", "PEM (PKCS#1 or SEC1)", "PKCS#8"; Ed25519 is OpenSSH only) and `newKey.publicFormat` →
  `press title=Generate` → `wait until=sheet text="Key pair created"`: the fingerprint and the public key (in the
  format of `keyResult.format`) are the sheet's text; "Copy Public Key", "Install on Host…", "Show in Finder",
  "Export .ppk…", "Done".
- PuTTY keys: `press title="Import Key…" in="window:Keys" file=/path/key.ppk` (or drop it on the window, as a drag
  there does: `drop files=["/path/key.ppk"] target=keys`) → `importKey.ppkPassphrase` (an encrypted .ppk),
  `importKey.name`, `importKey.same` (keep the same passphrase; false: `importKey.passphrase` and
  `importKey.confirm`, empty for none) → `press title=Import` → `wait until=sheet text="Key imported"` (a wrong
  passphrase or a damaged file is the sheet's red text). Export (a version 3 .ppk: PuTTY 0.75 and later): select a
  key → `press title="Export for PuTTY…" in="window:Keys"` → `exportKey.passphrase`/`exportKey.confirm` (optional) →
  `press title=Export… in="window:Keys" file=/path/key.ppk` → the key's own passphrase may be asked (a sheet) →
  `wait until=sheet text="PuTTY key saved"`.

## settings
- `menu path="AirSCP > Settings…"` opens the Settings window (`in="window:Settings"`): `settings.appearance`
  (System, Light, Dark), `settings.terminal`, `settings.showHidden`, `settings.preserveTimes`,
  `settings.confirmDelete`, `settings.alwaysCalculateFolderSizes`, `settings.hostKey` (new hosts' server key, as
  hostEditor.hostKey), `settings.certificate` (new desktops' certificate, as rdpEditor.certificate; with a company
  certificate authority: `settings.caFile`, or `press id=settings.chooseCA in="window:Settings" file=/path/ca.pem`),
  the folder for new keys (`press id=settings.keyFolder in="window:Settings" file=/folder`; "Use ~/.ssh" goes back),
  in the App Store version the SSH folder (`press id=settings.sshFolder in="window:Settings" file=/Users/me/.ssh`: only
  a folder the user allowed already; see troubleshooting),
  `settings.agentControl` (turning it off ends
  agent control at once; `settings.mcpCommand` is the `claude mcp add` command it shows, `settings.copyMCPCommand`
  copies it), `settings.askBeforeAgentChanges` (changes wait for the person at the Mac, see overview: only they can
  change it, an agent's `set` or `press` of it is refused), `settings.debugLogging` (Advanced: the debug log, see
  troubleshooting). Downloads folder: `press
  title=Choose… in="window:Settings" file=/Users/me/Downloads`. It is where Download To… opens (its reply's
  `panelFolder`) and where Download as .tar.gz puts the archive when the other pane shows a server too.
- `snapshot include=["settings"]` reads them all. The window opens 600 points tall and its form scrolls; the controls
  work by id wherever they are, and `press`/`set` scroll theirs into view (a screenshot then shows it, e.g. `set
  id=settings.debugLogging value=false in="window:Settings"` for the Advanced section); `menu path="Window > Zoom"
  in="window:Settings"` shows as much of the form as the screen holds.

## rdp
- New desktop: `menu path="File > New Remote Desktop…"` → `rdpEditor.name`, `rdpEditor.hostname`,
  `rdpEditor.username`, `rdpEditor.password` (leave it empty to be asked), `rdpEditor.via` ("Connect through": an SSH
  host to go through), `rdpEditor.clipboard`, `rdpEditor.shareFolder`, `rdpEditor.folder`; under Advanced (`press
  title=Advanced`): `rdpEditor.port` (empty: 3389), `rdpEditor.domain`, `rdpEditor.display` (Fit the window, Fixed
  size, Full screen), `rdpEditor.cmdAsCtrl` (false: ⌘ is the Windows key), `rdpEditor.certificate` (Server
  certificate: "Ask (default)", "Trust automatically" (the first certificate is remembered without a question; a
  changed one is still asked about), "Don't check (insecure)", "Trust my company's certificate authority" with
  `rdpEditor.caFile` or `press id=rdpEditor.chooseCA file=/path/ca.pem`) → `press title=Add`. `press title="Test
  Connection"` logs in and out; with `rdpEditor.via` it connects that SSH host first, its questions as sheets on the
  editor.
- Connect: `select pane=sidebar names=["Windows VM"]` → `menu path="Host > Connect"` → certificate sheet ("Trust the
  certificate of …?": press "Always Trust" or "Trust Once"; none under Trust automatically or Don't check, nor for a
  certificate the chosen company authority signed; "The certificate of … has changed" always asks) → login sheet (`rdpLogin.username`, `rdpLogin.password`,
  `rdpLogin.remember`; press "Log In") → `wait until=rdp_connected` → `wait until=rdp_drawn` (Windows draws a blank
  frame first, for up to a minute at logon). Questions for a desktop that isn't shown come on the window too. `snapshot`
  → rdp: state, size, fullScreen, sharing, sharedFolderReady, sharedFolderRefused, remoteFiles, message.
- Drive Windows with its keyboard first: keys don't miss, clicks can. `key {"combo": …, "target": "rdp"}` with
  "win+e" (File Explorer), "alt+d" or "ctrl+l" (Explorer's address bar: then `type {"text": "D:\\", "target":
  "rdp"}` and "return" opens that folder), "win+r" (Run: a program, a folder or \\tsclient\AirSCP, then "return"),
  "win" (Start: type to search, then "return"), "ctrl+shift+escape" (Task Manager), "alt+tab", "ctrl+w" (closes an
  Explorer window), "alt+f4" (closes the window; on the bare desktop it offers to shut Windows down: "escape"),
  "tab", "shift+tab" and the arrows (move in a dialog or a list; in a folder, type a name's first letters to select
  it), "return" (opens it), "alt+up" (the folder above), "f2" (rename), "ctrl+a", "ctrl+c", "ctrl+v". "cmd" is Ctrl
  too ("cmd+c" copies) unless the desktop's ⌘ is the Windows key; "capslock" lasts until the next desktop action,
  which gives Windows the Mac's own Caps Lock again. Ctrl+Alt+Del: `press title=Ctrl+Alt+Del`.
- See it: `screenshot target=rdp`, the desktop alone at its own pixel size (the reply gives it): read Windows' text
  there, and look again after each step. Windows opens a window a moment after its key: keys sent before it shows go
  elsewhere (typed on the bare desktop, then "return", they open whatever icon the letters chose), so after "win+e"
  or "win+r" take screenshots until it is there, then type.
- Click only what no key reaches: `click {"target": "rdp", "x": …, "y": …}` in pixels of that picture, from its top
  left; `"count": 2` double-clicks, `"button": "right"` right-clicks, `"wheel": -3` scrolls down three notches there.
  The reply's picture shows what was there, zoomed, with a red cross where it clicked: when the cross isn't on what
  you meant, take a new screenshot before clicking again. (Without target, x, y are the main window's points.)
- Full screen: `press title="Full Screen"`, `menu path="View > Enter Full Screen"` or `key combo=ctrl+cmd+f
  target=rdp`; each leaves it again (the menu item and the bar's button are titled Exit Full Screen then). `snapshot` →
  rdp.fullScreen; `screenshot` then draws the full screen, with the note at its top for the first seconds ("Press ⌃⌘F
  to leave full screen").
- Files to Windows: `drop files=[…] target=desktop` copies them into the shared folder, \\tsclient\AirSCP in
  Windows (`wait until=text text="In Windows:"`). Files from Windows: copy them into \\tsclient\AirSCP in Windows; they
  appear in the Mac folder (~/Downloads/AirSCP RDP unless the entry names another). The bar's "Send Files…" copies Mac
  files there too (`press title="Send Files…" files=[…]`). "Paste N Items to Mac…" copies
  what Explorer copied into a Mac folder: `press id=rdp.pasteItems file=/Users/me/Downloads` (its title counts the
  items: see snapshot.rdp.remoteFiles). "Shared Folder" opens Finder. Disconnect asks first while Windows
  copies into the shared folder (the cut-off files are removed). `press id=rdp.copySharedFolder` puts
  \\tsclient\AirSCP on the clipboard (for Explorer's address bar).
- Windows' settings can turn drive redirection off (Group Policy): `sharedFolderRefused` is true, \\tsclient is empty
  there, and drops and Send Files… are refused. Copy and paste files instead (below) when Windows allows the
  clipboard: the bar then says so.
- Clipboard: the desktop has the keyboard focus only while a `key`, `type` or `focus target=desktop` runs, as if
  clicked and then left: the Mac's clipboard goes to Windows then (text, or files), and what Windows copied comes to
  the Mac when it ends. Files Mac → Windows: select them in the left pane (this Mac) → `menu path="Edit > Copy"` →
  show the desktop and `focus target=desktop` (Windows gets the copy) → in Explorer `key combo=cmd+v target=rdp`. Windows → Mac: copy in Explorer
  (`key combo=cmd+c target=rdp`); snapshot.rdp.remoteFiles counts them; AirSCP fetches them (up to 256 MB) onto the
  Mac's clipboard after your next desktop action or `focus target=sidebar` (`wait until=text text="on the Mac's
  clipboard"`), and `menu path="Edit > Paste"` in a server pane uploads them.
- Disconnect: `menu path="Host > Disconnect"`.

## troubleshooting
- "AirSCP isn't running, or agent control is off": start AirSCP and turn on Settings ▸ "Allow AI agents to control
  AirSCP (MCP)". The bridge talks to the AirSCP of its own settings folder (AIRSCP_SUPPORT_DIR, when set). "AirSCP
  didn't answer": it is busy with many calls at once, or quitting; check with snapshot before doing it again.
- A connect or transfer fails and its message doesn't say enough (often through a proxy or a jump host): turn on the
  debug log with `menu path="Help > Turn On Debug Logging"` or `set id=settings.debugLogging value=true
  in="window:Settings"` (or, in the "Can't connect" sheet or a Disconnected banner,
  `press title="Turn On Debug Logging and Try Again"`, which connects again), make it happen again, then read the
  plain-text file at `snapshot` → debugLog.path. Each line has the time and the host.
  "Couldn't connect: it stopped at …" names the hop that failed (the proxy, the jump host or the server) in plain
  words; the lines before it are ssh's own (-vv: "Authenticated to bastion", "channel 0: open failed"), the proxy's
  answer ("proxy-connect: the proxy 127.0.0.1:3128 answered CONNECT bastion:22 with “HTTP/1.1 407 …”") and the
  questions ssh asked (never the answers: no password is ever in the file). `menu path="Help > Copy Diagnostics"`
  copies the versions and the log's last lines; "Help > Show Debug Log in Finder" shows the file to the user. Turn the
  log off when done: `value=false`, `press id=debugLog.turnOff` (the sidebar's Turn Off) or
  `menu path='Help > Turn Off Debug Logging'`. AIRSCP_DEBUG=1 in AirSCP's environment turns it on from the start (and
  keeps it on).
- Questions to the person at the Mac (Settings ▸ "Ask before agents change things", on unless they turned it off).
  These wait up to 45 s for their Allow Once, Allow for 15 Minutes (no more questions until then) or Deny: a request
  that deletes, replaces or renames files (Rename's button), copies them (`drop`, Upload…, Download…, Paste,
  Synchronize; on S3 storage also Compress…, Extract Here and Extract to New Folder), makes an S3 presigned link, opens
  a file in its app, changes permissions or owners (Permissions' Apply, Make Executable), puts a key on a server (Keys'
  Install) or in the ssh agent (Add to Agent), switches a tunnel on or off, runs a command, a file or a snippet, kills a
  process, disconnects, quits, cancels, retries or resumes transfers, types text (a snippet, a History or Insert Path
  entry too) or presses keys in a Terminal tab, types, presses keys or clicks on a Windows desktop, or presses a button
  that a question marks as destructive (Delete, Replace, Kill, Close Tab…). A question AirSCP asks itself (Delete's) comes
  first, as always: its Delete button is what waits. Looking, selecting, going to folders, opening AirSCP's own sheets
  and typing into its fields never wait, and only the person can turn the setting off.
  "The person at the Mac declined: <what>": they said no; nothing was done. Don't try it another way (another tool or
  menu): tell the user what you wanted to do and why. "The person at the Mac didn't answer within 45 s: <what>":
  nothing was done; ask the user to look at the Mac, then try once more. "What … acts on changed while the person at
  the Mac decided": the selection or the question changed meanwhile; nothing was done: `snapshot`, then try again.
  "Agent control was turned off: nothing was done.": the user ended agent control while a question waited.
- "… is disabled now: <reason>": the reason says what is missing (no selection, not connected, sftp only, the Files
  tab not shown…).
  "Nothing to press called …" / "No field …": `snapshot include=["sheets","elements"]` shows what is there (add
  `in="window:<title>"` for another window).
- A `wait` that stops with "a sheet asks something": answer that sheet (it is in the reply), then wait again.
- Sheets queue: a second question appears when the first is answered. `wait until=no_sheet` after the last one.
  `key combo=escape` cancels a question with Cancel; `press title=OK` closes a message with only OK.
- Menus are never in screenshots (they open only for a person): read `snapshot include=["menus"]`.
- File > Find Files… searches a server's folders (focus the server's pane); File > Disk Usage… measures the folder a
  pane shows (a server with a shell, or this Mac) below it; File > Synchronize… needs this Mac in one
  pane and a connected server in the other. `wait until=found` / `compared` needs its sheet open.
- Synchronize compares times as the server lists them: to the minute (the day for files over six months old, or dated
  after the server's clock: those count as newer), so two versions with the same size saved within one minute count as
  the same. The panes' rows then have `modified` as a day only ("2024-01-01"). A folder it can't list stops it (failure).
- A retry that started from 0 (no `"resumed": true`): sftp couldn't continue the kept part (gone, or not smaller than
  the file), so the file was copied again.
- Typing goes to the focused field: `focus` it, or use `set`, which focuses and replaces the text.
- Every tool works with AirSCP behind other windows: AirSCP isn't brought to the front (keys and clicks go to its
  windows directly). A click on a list row may not select it then (AppKit takes it as the click that activates the
  window): never click rows. Use `select`, `open` (a double-click on a file row), `go` (a folder by its path), and
  `focus target=sidebar` + `key combo=return` (a double-click on a host: it connects and shows its files).
- While the Mac's screen is locked, full screen, window tiling (Move & Resize) and animated toggles (Hide Sidebar)
  wait until it is unlocked, though the reply says ok; the Monitor refreshes only while you are at work (a `wait`).
- Screenshots draw AirSCP's own windows: a table's header can show the rows scrolled under it, the toolbar and the
  sidebar have no glass, and menus are never in them. A host's state is in `snapshot` (sidebar).
- The App Store version (its Settings window has `settings.sshFolder`) runs in Apple's sandbox. It opens only the
  folders of this Mac the user allowed, and `file=` can't allow one: only the user's own choice in an Open panel does.
  A Mac folder it may not open yet fails with "Operation not permitted": ask the user to open it once in this Mac's pane
  (AirSCP then asks them to allow it), or to choose their SSH folder in Settings ▸ Keys. Import from ~/.aws asks them
  to allow their .aws folder the first time. Open Terminal, Open Terminal Here, Run in Terminal and Kill with sudo use
  the host's Terminal tab (as `settings.openTerminalHereInTab` does in the other version, which this one doesn't have).
  From a shell, `--out file.png` saves only in AirSCP's own container: use `--out -`. Its screenshots draw a window
  behind other apps as inactive.
- Quit (`menu path="AirSCP > Quit AirSCP"`): refused while a sheet is open; it asks first while transfers run or an
  editor has unsaved changes (the reply is that question), else it answers `quitting` and AirSCP quits.