An emulated SSH login for Pantheon sites
PanSSH emulates an interactive SSH connection to a Pantheon site's application environment using only their available (limited) SSH service. It provides command history, local editing of remote files and an emulated current working directory.
You can do almost everything that you could if a standard SSH login were available, and it looks and feels so familiar that you may not notice the difference.
Download and run the main script
curl -so panssh https://github.com/andy-netgenius/panssh/raw/refs/tags/latest/panssh
chmod +x panssh
./panssh
Further instructions will then be displayed.
- 1.3.1:
- Added
.copy,.copyrand.rsyncbuilt-in commands to copy/sync directories to/from the remote site. - Various minor fixes and improvements.
- Added
- 1.2.1:
- Added .lando.panssh.yml, which provides easy setup of PanSSH in a Lando project.
- Improved handling of syntax errors in bash commands.
- 1.2.0: Tab-completion is now included, on supporting systems:
- Local site and environment names.
- Remote directory and file names.
panssh site.env
panssh site.env "command1; command2; ..."
panssh site.env < script.sh
echo "commands" | panssh site.env
site— the Pantheon site name.env— the environment identifier (dev,test,live, or multidev ID).
- Use shell commands in the normal way.
- Type
exitto close the interactive session.
-
.help— Display usage information and command list. -
.vw <filepath>— View a remote file (download and open in viewer/editor). -
.ed <filepath>— Edit a remote file (download, edit locally, upload). -
.ls— Toggle automaticlsafter directory change. -
.copy [local:]<source> [local:]<target>— Copy files to/from the remote site. -
.copyr [local:]<source> [local:]<target>— Recursively copy directories/files to/from the remote site. -
.rsync [options] [local:]<source> [local:]<target>— Run rsync.
-
The
.copycommand runs rsync with itspreserve modification times,compressandprogressoptions enabled. -
The
.copyrcommand adds rsync'srecursiveoption, but is otherwise identical to.copy. -
The
.rsynccommand runs rsync with only the options you specify.
All three commands require that either the source or target path be prefixed by local: in order to indicate the required transfer direction.
Examples:
To the copy the local file settings.php to the remote current directory you could use:
.copy local:settings.php ./
To recursively copy all files and sub-directories from remote path web/sites/default/files/ to local path /tmp/files/ you could use:
.copyr web/sites/default/files/ local:/tmp/files/
- A Pantheon user account with SSH access configured.
- SSH client with a key pair registered in your Pantheon account.
- Bash 3.2+ for basic operation.
- Bash 4.0+ to support tab-completion of remote directory and file names.
- Common Linux/Unix utilities.
- For local file viewing / editing:
- Either
nanoorvimavailable via$PATH$ , or a suitably configured$EDITOR. - Standard
scpandshasumutilities.
- Either
- For copying files to/from remote: rsync.
- Terminus CLI (needed only to fetch a list of your accessible sites).
The only required file is the panssh script.
curl -so panssh https://github.com/andy-netgenius/panssh/raw/refs/tags/latest/panssh
- Mark the script as executable:
chmod +x panssh - Run it as just
./pansshto see further instructions.
Clone the PanSSH repository or download and unzip the zip archive.
Mark the main panssh script as executable, then copy or move it to any suitable directory that's included in your PATH.
chmod +x panssh
sudo mv panssh /usr/local/bin/
Run it as just panssh to see further instructions.
Copy the panssh completion script from bash-completion/ to the bash-completions/completions directory on your system.
- For recent Ubuntu distributions, you can probably use
/usr/local/share/bash-completion/completions/ - For MacOS, maybe
/opt/homebrew/etc/bash_completion.d/orusr/local/etc/bash_completion.d, depending on your system.
Test tab-completion by entering panssh then pressing the tab key (create a sites configuration file first).
This feature requires Bash 4 or higher.
- On MacOS:
- You can install Bash 5 with Homebrew.
- You will also need bash-completion or bash-completion@2
Copy readx.source.sh to one of:
- The same location as the main
pansshscript. - A subdirectory
../lib/pansshrelative to the location of the mainpansshscript.- For example:
/usr/local/lib/panssh/ifpansshitself is in/usr/local/bin/
- For example:
Test tab-completion by using panssh to connect to a Pantheon site, then press the tab key once or twice - the remote directory contents should be listed.
A simple CSV file holding name and ID of the sites you want to connect to is required at:
$HOME/.panssh.sites
To generate or update it, run:
terminus site:list --format=csv --fields=name,id > $HOME/.panssh.sites
This file maps Pantheon site names to their site IDs, which are used to form SSH host and user names.
- Most things will just work as you would expect. A few won't (see limitations, below).
- Local viewing and editing of remote files, with automatic download and upload.
- Non-interactive execution from local scripts or piped input.
- Arrow-key command history for the current session.
- Local tab-completion of site and environment names.
- Tab-completion of remote directory and file names.
- Optional automatic listing of directory contents after switching directory.
- Uses persistent SSH connections for best responsiveness.
- No support for interactive input (
more,rm -i,drushconfirmation prompts, etc). Some such programs will act as if ENTER was pressed and use a default value. Others will simply not work. - Some behaviours will differ compared with a real interactive SSH session.
- Tab-completion for remote directory and file names requires Bash 4+.
- Relies on discoverable but publicly undocumented features of Pantheon's SSH service, and their user and host naming conventions.
Andy Inman
ainman@netgenius.co.uk
MIT