Command Line

Command Line

SSH Pilot can be started from a terminal, and pointed straight at a server the way you would point ssh at one. Two more commands let you check on, and script, the background service that holds your connections.

Command	What it is for	Where you get it
sshpilot	Start the app, optionally opening a server	Every install
sshpilot-daemon	Check, stop or restart the background service	Linux packages, AppImage, Flatpak
sshpilot-cli	List connections and run commands on them from scripts	pip installs and the Windows bundle

---

Opening a server: sshpilot

Anything after SSH Pilot's own options is read like an ssh command line:

sshpilot web                                 # a Host alias from ~/.ssh/config
sshpilot root@example.com
sshpilot -p 2222 user@host
sshpilot -i ~/.ssh/id_ed25519 user@host
sshpilot -p 2222 -i ~/.ssh/id_ed25519 -J bastion user@host
sshpilot ssh -J bastion user@host            # a leading "ssh" is optional
sshpilot --sftp user@host                    # open in the File Manager instead

• A saved Host alias opens that connection, with everything it is set up with (keys, jump hosts, port forwards, commands).
• Anything else opens in a new tab without being saved. If that server is not in your SSH config yet, SSH Pilot offers to save it once it connects.
• ssh options pass straight through. SSH Pilot has no -v or -q of its own, so sshpilot -v user@host gives you OpenSSH's verbose output.
• Only ssh is wrapped. scp, sftp, rsync and ssh-copy-id command lines are refused.

When SSH Pilot is already running

The server opens as a new tab in the window you already have, and the command returns straight away. Nothing else starts.

Exit status

Status	Meaning
0	The app started, or the server was handed to it
2	SSH Pilot's own options could not be parsed
255	The destination was refused or could not be opened

On 255 the reason is printed on the terminal and no connection is started, like ssh. A launch made only for that destination quits again. The one exception is when the background service cannot be reached: the window then stays open, so you can retry it from there.

$ sshpilot scp a b
sshpilot: Only SSH commands are allowed. Example: ssh user@host
$ echo $?
255

Flatpak

Pass the same arguments after the app ID:

flatpak run io.github.mfat.sshpilot user@host

---

Options

Option	What it does
--sftp	Open the destination in the File Manager instead of a terminal tab
--isolated	Switch to Isolated Mode. The switch is saved: later launches stay in Isolated Mode until you choose Default Mode in Settings → Advanced → Operation Mode
--verbose	Debug logging, for this run only
--quiet	Only warnings and errors, for this run only
--diagnostics	--verbose plus GTK/GLib info and debug messages. Use it when reproducing a bug
--log-gtk-warnings	Also capture lower-severity GTK/GLib messages
--fatal-warnings	Stop at the first GTK/GLib warning, with a full backtrace in crash.log
--version	Print the version and exit
--help	Print the options and exit

--diagnostics only makes the logs more detailed. To get a file you can attach to a bug report, reproduce the problem, then use Help ▸ Export Diagnostics…, which saves a sanitized ZIP.

---

Files and environment

Path	Contents
~/.ssh/config	Your connections (Default Mode)
~/.config/sshpilot/config.json	App settings, including the operation mode
~/.local/state/sshpilot/	Logs: sshpilot.log, app.log, ssh.log, daemon.log, crash.log

The Flatpak keeps these under ~/.var/app/io.github.mfat.sshpilot/.

To keep SSH Pilot away from your real ~/.ssh (for a demo, or to try a different set of servers), point it at another directory:

SSHPILOT_SSH_DIR=~/sshpilot-demo sshpilot

---

The background service: sshpilot-daemon

Your connections, terminal sessions, port forwards and file transfers are run by a small per-user service. The app starts it when it needs it, and it stops by itself once nothing has used it for 5 minutes: no window or other client, and no session, port forward or transfer still running. You rarely need to touch it, but it helps when something is stuck:

sshpilot-daemon status        # is it running, and what is it holding?
sshpilot-daemon diagnostics   # status plus memory, open files and queue depth
sshpilot-daemon restart       # restart it
sshpilot-daemon stop          # stop it

Each prints JSON. status exits with 0 when the service is running and 2 when it is not.

If sessions, port forwards or transfers are still running, stop and restart refuse, exit with 1 and list what they would end. Add --force to end them anyway:

sshpilot-daemon --force restart

In the Flatpak:

flatpak run --command=sshpilot-daemon io.github.mfat.sshpilot status

---

Scripting: sshpilot-cli

sshpilot-cli talks to the same background service as the app, so it sees the connections, credentials and host keys you set up there. It does not start the service: open SSH Pilot first, or start it with sshpilot-daemon.

It is installed with pip install and in the Windows bundle (sshpilot-cli.exe). The Linux distribution packages, AppImage and Flatpak do not include it.

sshpilot-cli status                     # the service's state and counters
sshpilot-cli connections list           # id, name and target, tab-separated
sshpilot-cli connections show web       # one connection's details
sshpilot-cli sessions list              # open terminal sessions
sshpilot-cli exec web -- uname -a       # run a command, print its output
sshpilot-cli --json connections list    # JSON instead of text

A connection can be named by its ID, nickname, host or hostname, or by the name shown in the sidebar.

exec prints the remote command's output. If the server needs a password, passphrase or host key confirmation, it asks for it on the terminal, the same way the app would.

$ sshpilot-cli exec web -- 'echo out; echo err >&2; exit 3'
err
out
$ echo $?
1

Status	Meaning
0	Success
1	The operation failed. For exec, the remote command failed: the remote exit code itself is not passed through
2	Usage error, such as an unknown connection name
3	The background service is not running or not compatible

Also available: sshpilot-cli capabilities, and operations get / operations cancel for an operation ID.