Adopting new tools can be intimidating.
Whether this is your first venture into a Terminal application or it's just well outside your comfort zone, remember it takes time to get comfortable with new software -- put on your thinking cap and be patient, curious, careful and confident you can figure it out!
There's a lot of lingo to learn using a CLI. Shells, streams, SSH, strange symbols and a sea of acronyms...
This guide is designed to get you going with the command line so you can get going with WP-CLI.
This guide is far from comprehensive -- it's designed to get you going with WP-CLI, but in reality you don't need to be a CLI expert to make great use of WP-CLI or build custom WP-CLI commands using PHP.
Check out the resource section at the end to learn more about the Terminal and Command Line interfaces!
This guide is meant for Linux/Unix based systems (which includes MacOS, ChromeOS, Ubuntu, etc). While it's possible to host WordPress on Windows, most WordPress servers run Unix-like operating systems.
If you're a Windows user, this guide is likely still useful to you! Often when you're running WP-CLI, you'll be remotely-connected to an internet server or local, virtual server on your Windows machine that's running one of these Unix-like operating systems. Windows 10 also offers a system called Bash on Ubuntu on Windows (yes, a mouthful) which lets you use native Linux commands on your Windows machine.
- More flexibility
Most modern programming languages like PHP, JavaScript and Python can be used to create a CLI application -- just as these languages can be used to generate HTML documents for a web browser.
In a command line, these languages wrap three underlying application streams to create the CLI:
- STDIN - Standard Input
- STDOUT - Standard Output
- STDERR - Standard Error
Think of these technologies as the conveyer belts your data is carried on -- carrying data into your application, out of your application and a special error handler that stops the other belts and tells you the error for why they stopped.
When you type a command and hit return
, you're sending that input to STDIN
. Then, as processes are reporting progress or completion, they'll return output to STDOUT
. If something goes wrong, your application will send errors to STDERR
and break out of their process.
It's not super important to understand these underlying pieces deeply to use WP-CLI or write Custom WP-CLI Commands with PHP.
The are two critical concepts to understand while you're using a CLI in a Terminal window:
In a terminal session...
- ... you're always using a user account with varying permission rights to read or write to parts of the filesystem.
- ... you're always inside a folder (aka directory) somewhere on the filesystem.
When you open a Terminal window on a Mac or Linux machine you'll see something like this:
username@hostname:directory[separator]
In my case, this looks like...
dryan@mbp:~$
dryan
is my system user's username (which differs from my user's display name ofDavid Ryan
)mbp
is the name of my host machine~
is a symbolic shorthand for my user's directory (/Users/dryan
)$
is the "prompt" part of "command prompt" that separates your command from lets you know the Terminal is ready for input (>
on Windows) and has a cursor following it.
We'll get into more details below about how to navigate the filesystem, but for now know whenever you see that string, it means your terminal is awaiting input and no processes are running.
As mentioned above, when you first open a Terminal window you are in your user's Home Directory.
~
is short for the user's Home Directory (i.e./Users/dryan
).
is short for the current directory...
is short for the directory above the current directory./
when at the beginning of a path stands for the root directory of the entire filesystem (elsewhere it denotes the separation between directories)
With paths, similar to URLs, there are relative paths and absolute paths.
This is best explained by introducing the cd
command, which is used to change directory.
Example: Changing into a folder called playground
in my user's directory would be:
cd playground
but only if I'm in the root of my home directory. This relative path is relative to your current directory.cd /Users/dryan/playground
from anywhere (including my home directory). This absolute path can be used anywhere and doesn't take the current directory into account.
As directories change, you'll see your prompt prefix change as well:
dryan@mbp:~/playground$
Then, if I wanted to "step up" one directory to return to my user directory, I could run...
cd ..
Or, if I wanted to step up two directories into the /Users
directory from /Users/dryan/playground
, I'd run
cd ../..
TIP: For a long directory name that's inside the current directory (i.e. my-super-long-folder-name
) you can type the first few characters cd my-
and hit the TAB
key to auto-complete the name without typing it all out. This also works with absolute paths as-you-go:
cd /Users/dr
+TAB
(to getdryan
), and then...cd /Users/dryan/my-
+TAB
(to getmy-super-long-folder-name
)
macOS TIP: For a long directory path, you can type cd
(note the space) and then drag-and-drop a folder from Finder into the terminal window, which will insert the absolute path to that directory. It can save a ton of time over typing a path like cd /Users/dryan/Sites/VVV/wordpress/public_html/wp-content/plugins/src/scss
.
cd
- Change directoriesls
- List filestouch
- Create a filemkdir
- Create a folderrm
- Remove a file or folder&&
- Chain commands together
cd wp-content/themes && mkdir custom
Change into the plugins directory and force remove Hello Dolly, and recursively remove any subfolders and nested files inside hello
cd wp-content/plugins && rm -rf hello
cd .. && touch README.md
Change into the public_html folder (where WordPress lives) and list files, including hidden system files/folders that begin with a period
cd ~/public_html && ls -a
SSH stands for Secure Shell and works like a remote desktop for the Terminal.
SSH lets you connect to a shell session on a remote server with credentials. The server could be elsewhere on the internet, or simply a virtual server running on your local OS like VVV or Lando.
To access WP-CLI you will often need to "ssh in" to your server to begin running commands.
To use SSH you'll need:
- A username for a user on the remote server
- A hostname for pointing your computer at the server (either an IP address or domain like something.mydomain.com)
- A password or key file used to authenticate as that user.
(You may also need a port number, if the default SSH port 22 is blocked)
dryan@mbp:~$ ssh dave@192.168.32.145
Password: **********
dave@192.168.32.145:~$
If you've set a default User and key file in your ssh config, you can...
dryan@mbp:~$ ssh 192.168.32.145
dave@192.168.32.145:~$
A few things to keep in-mind when you're SSH'd into a remote server:
- You don't have access to command history from your local system.
- You don't have access to any aliases in your local system's
~/.bash_profile
-- you have your remote user's~/.bash_profile
- You only have access to software installed on the server, not on your local machine (i.e. you may be able to
npm install
on your local machine because you installednpm
on there, but that command may not work on your remote server unlessnpm
is installed there.)