Basic concepts and first run

Basic concepts and first run

WordShell works with nicknames for your websites. You enter a shortened name for the site the very first time you work with that site – and afterwards you refer to that shortened name. In this manual, we mostly use “mysite” as our example nick-name.

The first time you run WordShell, it will first ask you for permission to create a directory to store its internal data and configuration in. You should press Y to accept, twice:

Given working directory (/home/user/.wordshell) does not exist. This is normal if this is your first run and you should accept the option to create it now. Create? (y to create, other to abort): y
Given configuration file (/home/user/.wordshell/rc) does not exist. This is normal if this is your first run and you should accept the option to create it now. Create? (y to create, other to abort): y


Entering site details

If you have the requirements (see above), then you can begin to run wordshell for proper use. Run it with no extra parameters (or with the single parameter –addsite), and it will ask to take the details of the site you want to manage. First it will ask for the site’s web address (URL):

wordshell --addsite
New site: enter site URL, e.g. http://www.example.com (or 'none'):

If you enter “none” then several features will be unavailable, so this is not recommended. You should only enter “none” if you do not have HTTP access to the site.

Make sure you enter the site’s canonical URL (which you can find  in Settings -> General in the WordPress administration centre). Do not enter a URL which redirects to the site, but the canonical URL only.

If your site is protected by an HTTP password (i.e. if you visit in a web browser, then the browser throws up a username/password prompt), then you can include this in the URL like so: http://username:[email protected] Alternatively, you can include a line in your .netrc file (see “man netrc” for more information; a typical line looks like: machine www.example.com login myusername password mysecret).

Next, you will be asked how WordShell can reach the site’s files; whether through the local filesystem, or via FTP (of whatever kind), by SFTP; you should press 1, 2, 3 or 4 according to the answer:

Access by FTP, SFTP or filesystem? [1=FTP, 2=SFTP, 3=Filesystem]:

You will then be asked for further access details. e.g. For FTP you will be asked to indicate the encryption type (don’t worry, there is a default that works in most cases), and for the hostname, username, password and directory; for filesystem access you will be asked for the directory. Finally, you will be asked for a nickname to use to access this site in future (use alphanumerics and periods only in this nickname):

Access by FTP, SFTP or filesystem? [1=FTP, 2=SFTP, 3=Filesystem]: 1
Choose FTP encryption method [1=use encryption when available (a.k.a. explicit encryption) - recommended choice if you are unsure, 2=require explicit encryption (TLS), 3=never use encryption (recommended only for broken or local servers), 4=use FTPS (a.k.a. implicit encryption, usually port 990, becoming obsolete): 1
Enter host name (and optional port, e.g. ftp.example.com:2000) : ftp.example.com
Enter username : myuser
Enter directory : /htdocs
Enter password:
Enter a site name to save these details for later use: mysite

WordShell will then test access to the site using these details. If successful, it will save the details for later use. It will then show you a list of plugins installed on the site. If you do not wish to update any, then you can quit by pressing Control-C.

Adding sites non-interactively

It is possible to add sites to WordShell non-interactively, though be aware that you will need to make sure yourself that the site details are correct before you enter them. See the question “How can I automatically add my new sites to WordShell?” in the FAQs.

Expert tip: WordShell uses either lftp or curl for its FTP operations. lftp is preferred. If you have some special options you need, then you can configure them in /etc/lftp.conf or ~/.wordshell/lftp/rc. Furthermore, lftp uses the normal ssh binary for its SFTP operations; so you can also use configuration in ~/.ssh for SFTP sites.

The next step is to learn a few easy site management commands.

Chapter index: Starting to use WordShell