WP-CLI is a rather splendid command-line method of interacting with your WordPress site. You can use it to automate installs, update plugins and all sorts. At WordPress VIP, clients use it, in particular, to power batch updates – maybe some image compression that they’ve not done in the past, re-categorising articles, all sorts.

If you’re using WordPress and don’t use WP-CLI, I would highly recommend checking it out (especially so if you’re looking for a job in the VIP team 😉). However, this post isn’t about using it but to give recommendations on how to best write your scripts.

As I mentioned, VIP clients use WP-CLI scripts regularly – they can’t run them themselves but add the appropriate code to their site and we then run them from a sandbox on their behalf. What this means is that the whole process is handed over to us, so we will often see circumstances where scripts could have been giving more useful information to anybody running it. Away from VIP, these scripts will often be run by the very same developer so useful feedback from the script is forgotten about. When that then needs to be run in their absence, that’s when any failings will be found.

So, in no particular order, here are a few things I’d suggest considering for any WP-CLI script that you write.

1. Comment well and provide clear usage instructions. It’s important to be very clear about what each part is doing and why- commenting each step of your logic is a good sanity check. Comments are especially helpful when something maybe doesn’t work as intended and you need to debug to figure out why (which may occur some time after you originally wrote the code).
2. Consider a “dry mode” option. This is pretty much required for a VIP script and allows the script to be run first without any updates being made (the script runs normally but just omits any actual updates). This should be on top of running the script first in a test environment (development or, preferably, preprod).
3. Provide a summary at the end with all results of the script. Only yesterday I ran one that took about a second in total before returning back to the command prompt – no output and, therefore, no confirmation that it had even worked.
4. If the script takes a long time to run consider additional options to help if it doesn’t complete successfully and needs to be restarted (reboots happen folks!). To this end, allow parameters to allow it to be restarted from a particular point (if the script can’t automatically work out how far through it’s got) and consider output that will detail progress (e.g. if something works through a series of dates you may want to output each date as it is processed).
5. Keep output to a minimum. For somebody running it, it can be a blur of text which won’t be relevant and could mask anything which is actually useful – progress information or even errors. If all that additional output is required, think about getting the script to automatically dump this to a file instead.

That’s it. If I had to summarise all of this, I’d say assume somebody else is running it, it fails and they need to debug it and then re-run the script again. Make that as easy as possible and, even if it’s something only you ever use, you could be thanking me one day 😉