A Workaround for Using Local's Site Shell on Linux

For quite some time the “Site shell” button in Local has not opened a shell for me. I have come across many suggestions but none worked. Some have suggested that Local expects you to be in GNOME. If that is true, I do not know. I use Debian or Ubuntu with the KDE desktop environment. This is a workaround that I found for getting access to the site shell for each of my Local sites.

The workaround

Start up Local as you normally would and start a site. Then open a terminal and navigate to ~/.config/Local/ssh-entry/. This directory may have a bunch of .bat (for Windows) and .sh (for Linux) files with random names. Unfortunately Local does not clean up this directory when you delete a site. Fortunately, it will recreate the file if it gets deleted. So delete all of the files in this directory. This will help figure out which file is for the current site you are working with.

cd ~/.config/Local/ssh-entry/ # Change to the Local ssh-entry directory.
rm ./* # Remove all files in this directory.

The directory should now be empty. Go back to Local and use the “Site shell” button. Nothing will seem to happen. Go back to the terminal and list the files in the ssh-entry directory using the ls command. You will now see two new files. These are the shell files for your site. Execute the .sh file.

./iEgU7xg2I.sh # Run the script

It should output something like the following.

Setting Local environment variables...
----
WP-CLI:   WP-CLI 2.11.0
PHP version 8.2.23 (/home/yourusername/.config/Local/lightning-services/php-8.2.23+0/bin/linux/bin/php)
Run the "diagnose" command to get more detailed diagnostics output.
Composer: 2.8.6 2025-02-25
PHP:      8.2.23
MySQL:    mysql  Ver 8.0.35 for Linux on x86_64 (MySQL Community Server - GPL)
----
Launching shell: /bin/bash ...

You are now operating with environment variables set up for the current WordPress site in Local. Now you can use WP-CLI by running wp and anything else related to this site. If anything you would normally use (e.g. git) is not working as expected, just open another console window and do it there.

Referencing each shell file for a site

Take a look at Local’s sites.json file.

cat ~/.config/Local/sites.json | jq # Outputs the file with nice formatting

You will see that the ID of each site corresponds to the filenames of the shell files in the ssh-entry directory. In the future, you can refer to this file to find out which .sh file to execute for a desired site.