Use WP-CLI for repeatable administration by making the target, command and verification evidence explicit. Begin with read-only environment checks, inspect the installed command’s help and separate a preview from an authorised change. A useful runbook should let another administrator identify what ran, against which installation and how the result was checked.
Start with one bounded task rather than a long shell script. Write the intended outcome and identify the WordPress installation, operating account and environment. A command that behaves correctly against a test copy can still be unsuitable when its target or permissions are different, so those details belong in the procedure.
What should you inspect before a command changes anything?
The WP-CLI command reference describes discovery tools. The WP-CLI command family can review environment information and aliases. wp cli version prints the installed WP-CLI version. wp cli info reports details of the WP-CLI environment. Retain those observations when checking whether a procedure applies to the installed tool.
wp cli has-command detects whether a command exists. wp cli cmd-dump lists installed commands as JSON. Use the actual installed command set when preparing a runbook, particularly where packages or application versions differ. A command shown in an example should be confirmed before it becomes a dependency in an automated procedure.
WP-CLI aliases can be retrieved, set and updated. Review the alias destination where aliases are part of the arrangement. Make the target understandable in the evidence record so another administrator can distinguish the test installation from the live site before considering a change.
Keep credentials and private environment details in the approved operational store. The review record should identify the target and relevant configuration without copying secrets into documentation, terminal transcripts or a public article. Decide what information needs redaction before sharing the result.
How should command arguments be reviewed?
The WP-CLI quick-start guide explains the syntax. A command synopsis defines positional and associative arguments. Square brackets in the documented synopsis identify optional arguments. Read the synopsis for the installed command and record the arguments that determine the proposed scope.
WP-CLI provides global arguments shared by commands. Distinguish those from command-specific options when reviewing an example. Ask the maintainer to explain how the chosen options affect the target and output, rather than copying a command whose behaviour nobody on the team can describe.
Prefer a short, reviewable procedure with an observable result. State the precondition, the proposed action and the evidence expected afterwards. If a command depends on another step, make the dependency explicit so a failed prerequisite cannot be hidden by a later success message.
| Runbook question | Information to retain | Review result |
|---|---|---|
| Which installation is targeted? | Agreed path, environment and alias context | Reviewer can identify the intended site |
| Is the command available? | Installed version and command discovery | Procedure matches the actual tool |
| What defines the scope? | Reviewed synopsis and selected arguments | Intended records or operation are clear |
| Can the change be previewed? | Command-specific supported preview | Reviewer can inspect the proposed effect |
| What proves the outcome? | Relevant state and application-level check | Result matches the written requirement |
This original runbook worksheet connects command execution to a meaningful acceptance question. Keep the result tied to the specific operation instead of treating every successful exit as proof that the whole application works.
What does a dry run establish?
The quick-start guide documents a dry run for search and replace. Use that as a command-specific example: inspect the proposed replacement scope before deciding whether the corresponding write is appropriate. Confirm the installed command’s documented behaviour rather than assuming every WP-CLI command offers the same preview mechanism.
Record the proposed search and replacement values, intended environment and observed preview result. Review whether the selected values identify the actual migration task. A broad replacement can reach material the team did not intend, so the preview needs interpretation by someone who understands the records involved.
Keep the preview and write as separate events in the runbook. A reviewer should be able to see which evidence informed the authorisation and which later observation came from the approved change. If the target or inputs change, reassess the preview’s applicability before relying on it.
Prepare recovery in proportion to the action. Identify the material needed to recover the affected scope and who can carry out that recovery. This planning can be completed alongside the procedure without presenting an unperformed restore as a verified capability.
How should repeat runs and failures be handled?
Ask what should happen if the procedure is run again. The answer depends on the command and task: the second run may inspect an already-correct state, produce another change or require a different decision. Record the intended behaviour and test it in a separate copy where it matters.
Keep errors visible. Retain the relevant exit result and diagnostic output, then check the application state affected by the command. A script should not convert a failed operation into a reassuring summary merely because a later logging step completed.
Give partial completion its own recovery route. Ask which steps have already changed state and what evidence identifies them. The next administrator needs enough information to resume or recover deliberately, rather than guessing whether a repeated command will help.
Original two-target command review exercise
Prepare fictional test and release-target records for a proposed URL replacement, using a separate WordPress copy for any execution. The exercise follows environment discovery, command review, preview and application verification. It uses placeholder values and introduces no production command to run automatically.
First, ask the administrator to identify the intended installation and available command. Retain the tool version and relevant environment observations. Have another reviewer explain which target would be affected using the record alone; resolve any ambiguity before proceeding.
Next, review the installed command’s synopsis and the supported preview. Compare the observed scope with the written replacement requirement. Record excluded material and any unexpected match for investigation rather than broadening the requirement after seeing the output.
Then carry out only the approved test change and inspect the affected application route. Compare the result with the original requirement, retaining both command-level and application-level evidence. Ask how the procedure should behave on a repeat run and demonstrate that part where relevant.
Finally, review the runbook with the maintainer who will own it. Assign the recovery and escalation route, retain the tested version and inputs, and leave unresolved assumptions visible before the procedure is used in another environment.
For related work, see WordPress and hosting. Get started with the administrative task and verification evidence you need to make repeatable.
By Spout Team. AI-assisted drafting by Codex using the linked primary documentation.