Document guidelines for use of exit codes within commands

[Copilot]

WP-CLI lacked any documented convention for exit codes, leaving command authors without guidance on when to use non-zero codes or how to communicate them to script authors.

Changes

• New references/exit-codes.md — Reference page covering:

  • Standard codes (0 = success, 1 = failure via WP_CLI::error())
  • When to use non-standard exit codes (binary pass/fail results intended for shell conditionals) vs. when not to (informational outcomes like empty lists)
  • Shell scripting patterns using WP-CLI exit codes

• references.md — Added link to the new exit codes page

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Document guidelines for use of exit codes within commands</issue_title>
<issue_description>In wp-cli/doctor-command#125, @davegaeddert proposes to use exit(1) for any failed doctor checks. Similarly, @halfgaar asks to add a non-zero exit code in wp core check-update when updates are available (wp-cli/core-command#46).

We should document our guidelines for use of exit codes within commands. Ideally, a command should also be able to include annotation for possible exit codes and their meanings.

Previously: wp-cli/wp-cli#3577

Conversation in Slack today:

schlessera 8:13 AM The only other item that might be discussion-worthy is wp-cli/doctor-command#125 I think we should have a document that details how we decide on exit codes (and maybe a reference in some form). (edited)
8:13 For scripting, this is very essential.
8:14 The docblock parser should allow annotations for the exit code so we can generate a reference from that. (edited)
danielbachhuber 8:14 AM What's your opinion? At the moment, we only ever use 0 or 1. I've typically considered 0 to mean "WP-CLI performed the operation with success" and 1 to mean "WP-CLI was unable to perform the operation as expected"
8:15 Under these guidelines, the reporting in the doctor command would remain 0
8:15 I understand the practical benefit of switching to 1 for easier scripting
8:15 However, this would then be inconsistent with wp plugin list, wp core check-updates, etc.
schlessera 8:15 AM If WP-CLI is used for CI/CD, non-0 exit codes would halt the running process.
danielbachhuber 8:16 AM Right
8:16 which is a potential downside, because the script would need to explicitly accommodate for that
schlessera 8:17 AM When does wp plugin list return 1?
danielbachhuber 8:17 AM if WordPress isn't found, etc. (edited)
8:17 when listing installed plugins, it always returns 0
schlessera 8:17 AM Oh, yes, so that should halt the script.
danielbachhuber 8:18 AM hm, doctor already may accommodate this: wp doctor check --all --spotlight --format=count
8:18 if that is 0, no action is needed (edited)
schlessera 8:18 AM For the doctor command, I think it makes more sense to use it like PHPUnit or PHPCS.
8:19 In other words, the exit code should depend on the actual command that is being run, not on WP-CLI in general.
danielbachhuber 8:19 AM what about wp core check-update and wp cli check-update ?
schlessera 8:19 AM WP-CLI is but a framework, the commands are the actual tools the scripts use.
8:20 Good question. These might need a parameter to switch behavior, to accomodate for all use cases.
danielbachhuber 8:21 AM to unblock the doctor PR, let's first codify some guidelines in the handbook. I'll start a new issue in the main repo, and then someone can write a proposal.
schlessera 8:21 AM Yes.
8:22 I don't think we can find a simple rule that takes care of all use cases. But I do think we should have explicit reasons and a reference of possible exit codes somewhere.
8:23 Just like in the PHP reference, we should always be able to tell what the possible "return values" are.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Document guidelines for use of exit codes within commands wp-cli#4525

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.