yeremi / cli-standards
PHPCS standards for CLI command design, currently focused on WP-CLI code, with blocking and advisory sniffs for safety, automation, output, and documentation.
Maintainers
Package info
github.com/yeremi/cli-standards
Type:phpcodesniffer-standard
pkg:composer/yeremi/cli-standards
Requires
- php: >=7.4
- dealerdirect/phpcodesniffer-composer-installer: ^1.0
- squizlabs/php_codesniffer: ^3.7
README
PHPCS sniffs for CLI command design quality, currently focused on WP-CLI command code.
This package publishes the CLIStandards coding standard as a Packagist-ready Composer package. It enforces 18 checks derived from the CLI Standards model:
- 8 blocking checks reported as errors
- 10 advisory checks reported as warnings
Installation
composer require --dev yeremi/cli-standards
The Composer installer plugin registers the standards automatically. After installation:
vendor/bin/phpcs -i
You should see CLIStandards and CLIStandardsMust in the installed standards list.
Usage
Run the standard against your CLI command code:
vendor/bin/phpcs --standard=CLIStandards path/to/cli/
Useful variants:
# Show sniff codes. vendor/bin/phpcs --standard=CLIStandards -s path/to/cli/ # Enforce only MUST-level checks. vendor/bin/phpcs --standard=CLIStandards --warning-severity=0 path/to/cli/ # Emit JSON for CI tooling. vendor/bin/phpcs --standard=CLIStandards --report=json path/to/cli/ # Run only blocking rules. vendor/bin/phpcs --standard=CLIStandardsMust path/to/cli/
CLIStandardsMust is intended to behave like CLIStandards with warnings suppressed, which makes it useful for staged CI adoption.
Example Output
Anonymized example from a real local scan:
FILE: sample-plugin/includes/cli/class-command.php
----------------------------------------------------------------------
FOUND 4 ERRORS AND 3 WARNINGS AFFECTING 7 LINES
----------------------------------------------------------------------
9 | ERROR | Command name "sample-command" must include a namespace
| | (CLIStandards.CommandStructure.CommandRegistration.MissingNamespace)
24 | ERROR | Command docblock must contain a "## OPTIONS" section
| | (CLIStandards.Documentation.DocblockOptions.MissingOptionsSection)
25 | ERROR | Command docblock must contain a "## EXAMPLES" section
| | (CLIStandards.Documentation.DocblockExamples.MissingExamplesSection)
48 | WARNING | Consider using WP_CLI\Utils\get_flag_value()
| | (CLIStandards.Arguments.FlagExtraction.DirectAccess)
77 | WARNING | Bulk loop should use make_progress_bar()
| | (CLIStandards.Scalability.ProgressBar.MissingProgressBar)
----------------------------------------------------------------------
What It Enforces
Error-level sniffs:
CommandRegistrationFlagNamingOutputMethodErrorSeverityConfirmOnDeleteConfirmPassthroughDocblockOptionsDocblockExamples
Warning-level sniffs:
FlagExtractionStdoutStderrFormatSupportAvailableFieldsWpErrorHandlingDryRunSupportBatchProcessingProgressBarBatchSizeFlagSinceAnnotation
The implementation is intentionally heuristic in some areas. It favors practical signal over deep semantic analysis, so some checks can still produce false negatives or advisory-only warnings.
Scope
The standard name is generic, but the current implementation is not framework-agnostic. The sniffs are tuned for codebases that expose commands through WP_CLI, and most checks activate only when WP_CLI usage is detected.
Add To phpcs.xml.dist
<?xml version="1.0"?> <ruleset name="MyPluginStandard"> <description>Project coding standards.</description> <rule ref="CLIStandards"/> <file>./includes/cli/</file> <exclude-pattern>*/vendor/*</exclude-pattern> </ruleset>
Development
Install dependencies:
composer install
Run the fixture-based regression suite:
composer test
For contribution workflow and expectations, see CONTRIBUTING.md.
Repository Layout
CLIStandards/: the main standard and sniff classesCLIStandardsMust/: blocking-only variant for staged adoptiontests/Fixtures/: regression fixtures for expected violations and clean casesscripts/verify-fixtures.php: assertion-based test runner used by CI
License
See LICENSE (MIT).