Help page (wordshell –help)

Below is the output you get by running “wordshell –help”. If you are looking for the WordShell manual, then go here, or here for the general support page.

# wordshell --help

WordShell: www.wordshell.net (full manual and ticket system available online)

Tool for managing WordPress via the command line. Can operate on a WP install on the local filesystem or via FTP or SFTP. Various binaries are needed for full functionality; lftp in particular for FTP/SFTP; run with –checkrequirements for more information.

Usage: wordshell [<site-name>|all] [<plugin|theme|all>] (options)

Site names are aliases for sites whose fuller details are stored in the configuration file. If you enter an unknown site name, you will be requested for the site details and these will be added to the configuration file.

If you enter the site name ‘all’, then all sites that are in the configuration file will be processed (e.g. wordshell all –listupdates).

If you enter the plugin/theme as ‘all’, then all the plugins/themes on the indicated site are processed (e.g. wordshell mysite all –update –latest)

Backups are taken and versions are compared. If there any potential problems spotted then user interaction is required.

Meta-mode selection:
–plugin : Work on a plugin (this is the default mode, and does not need to be manually specified)
–theme : Work on a theme (e.g. wordshell mysite twentyten –delete –theme)
–core : Work on WordPress core. Not all operations are yet available, or make sense, in core mode.
–everything | -e : Precisely equivalent to running each of the above in sequence. Again, this does not make sense with every combination of options. It is most useful with –list or –listupdates.
–pluginsandthemes : Precisely equivalent to running with –plugin and –theme in sequence. Again, this does not make sense with every combination of options. It is most useful with –list or –listupdates.

Modes for performing plugin/theme/core operations (mostly mutually exclusive – you can only choose one mode at once):

–activate : Activate the specified plugin/theme (can be combined with install/update/rollback/restore)
–deactivate : Deactivate the specified plugin/theme (can be combined with update/rollback/restore; is automatically implied with –delete). These two switches are not applicable in core mode.
–changelog : Show the changelog for the indicated entity (requires w3m). If you also specify a site then after showing the changelog, move forward to the delete/install/rollback/update (otherwise stop).
–description : Show the description for the indicated entity (requires w3m). If you also specify a site then after showing the description, move forward to the delete/install/rollback/update (otherwise stop).
–downloadurl : Show the download URL for the indicated entity. If you also specify a site then after showing the description, move forward to the delete/install/rollback/update (otherwise stop).
–checkmodifications: Check entity for modifications compared with pristine version. This check happens automatically when updating; this switch is only for when you wish to do no other actions. If you wish to view the modifications, then specify –checkmodifications=view. Add showall to show status of all entities, whether modified or not (e.g. –checkmodifications=showall or –checkmodifications=showall,view). Note that when working with –core, only core WordPress files are checked; any additional files in your WP directory will be ignored (which includes wp-config.php).
–delete : Delete mode: does not ask for or upload new plugins/themes, simply deletes the files of the old one (WordPress will display an error next time you log in). Implies –deactivate unless you specify –skipdeactivate
–downloadonly : Download the specified entity from wordpress.org (into our internal cache, inside the working directory); do not update anything
–editconfig : Opens up the WordShell configuration in the configured text editor
–install : Install mode (uploads plugin; add –activate to also activate it)
–list : List installed plugins on the site. If you specify a plugin name, then this is used as a regex for matching; use –listexact to require an exact match. When the list is shown, a (-) next to the plugin name implies that the plugin could not be found at wordpress.org (hence either removed, or was third-party).
–login : Drops you into a shell or (S)FTP prompt in the site’s WordPress installation root
–rollback : Roll back to the most recently replaced version. If you optionally specify a time, then this will instead then automatically select the version of the plugin installed at that time, as far as we know. Any string supported by the ‘date’ command can be used here; e.g. –time=’last Tuesday’, –time=’10 days ago’, –time=’24 Feb’. Use –showrollbacks to see what is available.
–restore : Restores the current copy of the indicated entities. This differs from –rollback in that it restores the believed-to-be-current version from our local cache/backup (rather than any previously replaced version). This implies –cache –cache (as otherwise, if the site has been damaged, we would first replicate that damage to the local cache) and then you’d need to head to your backups). In fact, we assume that your site is damaged, and drop all sanity checks related to the currently installed entity and the backup you are replacing it from. With an undamaged site and up-to-date cache, –restore should result in no real changes. When operating upon core, this will restore whatever you backed up (see –justwp).
–update : Upgrade mode (this is the default if no other mode is specified; you only need to specify it manually if combining with –activate (–activate without –update does not perform a plugin update)). –upgrade is a synonym.

Modes for performing internal management/site management/checks (mutually exclusive – you can only choose one mode at once):
–checkrequirements: Checks that all possible helpers are available (lftp, rsync, diff, patch, unzip, vi, w3m), then exits
–deleterollbacks : Deletes all stored rollbacks older than 90 days, or the specified number (e.g. deleterollbacks=45)
–entermaintenance : Enter maintenance mode (add a parameter to specify a number of minutes, e.g. –entermaintenance=10; otherwise is indefinite)
–exitmaintenance : Leave maintenance mode
–waitmaintenance : Wait until the site is no longer in maintenance mode (but do not clear it ourselves)
–listrollbacks : Show possible rollbacks for a given site (and plugin/theme, if indicated)
–listsites : Show information on configured sites
–showpass : When used with –listsites, shows the passwords for (S)FTP sites
–maintenancestate : Show maintenance mode status
–addsite : Configure a new site (equivalent to specifying ‘new’ as the site and listing (–list))
–disablesite : Disable a site in the configuration file (but do not permanently remove it)
–enablesite : Enable a previously-disabled site in the configuration file
–refreshcache : Ensure freshness of our local cached copy of the site, then exit. You could use this to prime all the caches for quicker subsequent operation (e.g. in a cron job before your working day starts). If the cache was recently updated, then this is a no-op; to enforce an update, add –sync.

Mode-specific options:

Order of operations when working with multiple sites:
–groupbytype : If you choose to operate on all sites together with –everything or –pluginsandthemes, then this will order the operations/output by type (i.e. do the plugins on all sites, then the themes, then the core), instead of the default (which is to do all the plugins, then themes, then core on a single site, then move on to the next site, etc.)

Core operations:
–justwp : By default, when working with WordPress core, WordShell will ensure it has a backup of any files in your WordPress directory. This guarantees safety for disaster recovery (though note that current versions of WordShell only back up plugins and themes from wp-content, and nothing else from in there). However, it can be slow. If you know that you either have nothing else stored there, or that it does not need backing up, then you can supply this swtich. Note that this will NOT delete existing non-WP files from the local mirror (i.e. backups made when –justwp was not used). For that, add –justwpwipeothers.
–justwpwipeothers : This flag means the same as –justwp, except that back-ups of existing files that are not part of WordPress core will be deleted from the local mirror.
–filemethod : When upgrading to the latest WordPress version, by default WordShell will try to use WordPress’s built-in updating procedures, running on the remote website. Use this switch to instead upgrade via the filesystem. The built-in method is faster; files are more reliable if your site is broken and sometimes the only option if your web host has a very restrictive set-up. If you are not upgrading to the latest version, then this switch is redundant, as it is the only available method.

Install and update modes:
–latest : Synonym for –new=latest
–new=<file|version>: Either specify a particular version that can be downloaded from wordpress.org (e.g. –new=1.3.2), or a version of an already-known plugin/theme, or specify a path to a zip file to use (e.g. –new=myfolder/myplugin.1.9.zip). Only valid when a particular plugin/theme is specified. If you enter ‘latest’ then the latest version available from wordpress.org will be downloaded.
–trunk : When looking for the latest version, look in the development trunk, not at stable released versions (only relevant for themes/plugins from wordpress.org/extend). This will always require downloading from the trunk, so brings some slow-down.

Update mode:
–donotrequirenew : Do not abort the update if the chosen new plugin/theme’s version number is not newer than that currently installed (manual confirmation will still be required)
–autopatch : If the installed and plain versions differ, then automatically attempt to patch the new version appropriately (without asking first).

Delete, install, update, rollback and deleterollbacks modes:
–confirm : Ask an extra “are you sure?” question before going forward; this is useful if you want to use –changelog or –showchanges and perhaps back out if you do not like what you see.
–dryrun | -n : Skip the step of installing/deleting/updating/rolling back/(de)activating; only notify what would have been done
–thisoneonly : If the specified plugin/theme does not exist, then do not present a menu of existing plugins/themes; just finish
–skipdeactivate : In delete mode, skip the deactivation step

Update, rollback and restore modes:
–showchanges : Show changes from the installed plugin/theme to the indicated version. If you want to check to confirm the update after seeing the changes, use –confirm. This

List mode:
–listonlythirdparty: List only plugins/themes which were not found at wordpress.org (hence either removed, or obtained from elsewhere) (implies –list)
–listonlyupdates : List only installed plugins/themes for which an update is known to be available (implies –list)
–warnmissing : Prints a warning if no plugin/theme was found
–listexact : Turns off regex matching when listing – only list plugins that match the name exactly

List, update, restore and delete modes:
–active : Operate on plugins/themes only if they are active
–inactive : Operate on plugins/themes only if they are inactive
–currentversion=<ver>: Operate on entities only if the installed version matches this one. You can use –cver= as a shorter alias. This switch is also available in rollback mode. Prefix the version with x to negate the test, e.g. –cver=x3.3 means “not version 3.3”.

Verbosity options:
–debug | -d : Print lots of internal information. Specify twice or thrice for even more verbosity.
–showdiskspace : Show disk usage message at the end
–novaliditywarnings: Do not show warnings about plugin/theme sub-directories in which a plugin/theme could not be detected

General options:
–workdir : Working directory to use (internal data is stored here)

Debugging options:
–debug : Print lots of internal information. Specify twice for even more verbosity.
–disablecache : Disables relying on state of local caches (e.g. of WordPress API calls). Implies –sync.
–disableapi : Do not use WordPress’s API (http://api.wordpress.org) for any operations. This is mainly useful for debugging.
–disableremotecli : Miss out some (not guaranteed to be all) remote CLI calls
–disableftptls : For FTP sites, explicitly disables use of encryption (lftp option: ftp:ssl-allow no)
–requireftptls : For FTP sites, explicitly requires use of encryption (lftp option: ftp:ssl-force yes)
–sync : For (S)FTP sites, force initial sync of plugins/themes directory (i.e. do not skip sync if it had been synced recently). Use this if you know your local cache is out of date (e.g. a manual change was recently made at the remote side). See also –refreshcache.
–cache : For (S)FTP sites, force skipping initial sync of plugins/themes directory; use with caution. If specified twice, then does so also for filesystem mode sites.
–no(lftp|wget|curl|w3m|elinks|rsync): Behave as if the indicated binary does not exist on the system
–phpinfo : Get the phpinfo() output from the remote side
–phpversion : Get the phpversion() output from the remote side
–skipmakerollback : When deleting or updating, skip the creation of a rollback file (actually just skips some time-consuming step)
–testurl : Tests to see if a WordPress site exists
–remotecli : Drops into a CLI that allows you to run internal commands against the remote site. This mode is not officially supported; it is an internal interface which is not guaranteed between versions. Use –remotecli=<command> to run command non-interactively (can specify multiple times).
–workdir : Working directory to use (internal data is stored here)

Configuration management:
–setconfig : Set global configuration parameters, e.g. –setconfig=key:value. To set multiple parameters, separate with a comma, e.g. –setconfig=key1:value1,key2:value2
–getconfig : Read global configuration parameters, e.g. –getconfig=key1,key2,key3. Leave blank to show all.

Variables that can be configured:
ftpparallel : Default number of threads for lftp to use (lower this if you consistently find sites rejecting your connections for having too many at once). Can be over-ridden on a per-site basis if you add ‘/<number>’ to the site host name in the configuration file.
postfilecommand : A command that is run after newly installing plugins/themes in the filesystem, after selecting the new plugin/theme directory. e.g. “chmod 700 .” Do not use to perform a chown operation – that is already done automatically.
exclude-glob-ftp : A glob to match for files that should never be synced locally (e.g. if some plugin/theme stores an enormous amount of useless temporary data). Specify in a form compatible with lftp’s –exclude-glob option and separate multiple globs with spaces.
exclude-glob-rsync : A glob to match for files that should never be synced locally (e.g. if some plugin/theme stores an enormous amount of useless temporary data). Specify in a form compatible with rsync’s –exclude option and separate multiple globs with spaces.. If rsync is not installed, then this option has no effect (and thus such files will be synced).
curl-ftp-options : Command line options to add when curl is called for an FTP operation. Read the curl ftp man page for more information. Useful if you have some exotic authentication scheme. (To set lftp over-ride options, edit the file lftp/rc in your WordShell working directory).

Leave a Reply