WP-CLI Config Files: Best Practices Guide 2025

Typing the same WP-CLI flags repeatedly wastes time—--path=/var/www/html, --allow-root, --quiet on every command. Managing different configurations for development, staging, and production environments becomes tedious and error-prone.

Why Use WP-CLI Config Files?
WP-CLI Config File Basics
Project-Specific Configuration
Global User Configuration
Environment-Specific Configs
Advanced Configuration Options
Command-Specific Defaults
Security and Team Configs
Next Steps
Conclusion

WP-CLI config files automate command options, set project defaults, create custom aliases, and configure environment-specific settings. One wp-cli.yml file eliminates repetitive typing and standardizes WP-CLI behavior across your team.

In this guide, you’ll learn WP-CLI config file best practices, from basic setup to advanced configurations used by professional WordPress development teams managing multiple environments.

Why Use WP-CLI Config Files?

WP-CLI configuration simplifies command execution and ensures consistency across environments.

Problems Without Config Files

Repetitive flags: Typing --path, --url, --allow-root on every command.

Environment inconsistency: Different settings on dev, staging, and production.

Team confusion: Each developer uses different WP-CLI settings.

Command complexity: Long commands with multiple flags are error-prone.

No standardization: Can’t enforce best practices across projects.

WP-CLI Config File Advantages

DRY principle: Configure once, use everywhere.

Environment-aware: Different configs for dev, staging, production.

Team consistency: Everyone uses same WP-CLI settings.

Shorter commands: wp plugin list instead of wp plugin list --path=/var/www/html --allow-root.

Version controlled: Config files tracked in Git ensure reproducibility.

According to WP-CLI documentation, config files are essential for professional WordPress workflows.

WP-CLI Config File Basics

Understand WP-CLI config file locations and structure.

Config File Locations

WP-CLI searches for config files in this order:

# 1. Current directory and parents (project-specific)
./wp-cli.yml
../wp-cli.yml
../../wp-cli.yml

# 2. User's home directory (global defaults)
~/.wp-cli/config.yml

# 3. System-wide config (rarely used)
/etc/wp-cli/config.yml

Priority: Project-specific configs override global configs.

Basic wp-cli.yml Structure

# wp-cli.yml - Basic configuration

# WordPress installation path
path: /var/www/html

# Allow root user (for servers)
allow-root: true

# Site URL
url: https://example.com

# Disable colorized output
color: false

# Quiet mode (suppress informational messages)
quiet: false

# Debug mode
debug: false

Place in your WordPress root directory:

cd /var/www/html
nano wp-cli.yml

Test Config File

# Show current config
wp cli info

# Show which config files are loaded
wp cli info | grep "WP-CLI config"

# Test path setting
wp option get siteurl

Learn more in the WP-CLI config documentation.

Project-Specific Configuration

Configure WP-CLI for individual WordPress projects.

Complete Project Config

# wp-cli.yml - Complete project configuration

# Core settings
path: wp
url: https://example.com
allow-root: true

# Output settings
color: true
quiet: false
debug: false

# Command aliases
@staging:
  ssh: user@staging-server.com/var/www/staging

@production:
  ssh: user@prod-server.com/var/www/production

# Default parameters for commands
plugin list:
  - --format=table
  - --fields=name,status,version,update

theme list:
  - --format=table
  - --fields=name,status,version

post list:
  - --post_type=post
  - --orderby=date
  - --order=DESC
  - --posts_per_page=20

# Require specific WP-CLI version
require:
  - wp-cli/wp-cli: ^2.9

# Custom PHP binary
php: /usr/bin/php8.1

# Apache modules (for server info)
apache_modules:
  - mod_rewrite

WordPress in Subdirectory

# When WordPress is in a subdirectory

path: public/wp

# or
path: wordpress

# or
path: htdocs/wordpress

Custom Database Configuration

# Override database settings (for testing)

dbname: test_database
dbuser: test_user
dbpass: test_password
dbhost: localhost

# Use custom table prefix
dbprefix: custom_

Global User Configuration

Set default WP-CLI behavior for all projects.

Create Global Config

# Create config directory
mkdir -p ~/.wp-cli

# Create global config file
nano ~/.wp-cli/config.yml

Global Config Template

# ~/.wp-cli/config.yml - Global defaults

# Always allow root (useful for servers)
allow-root: true

# Color output enabled
color: true

# Show errors
debug: false
quiet: false

# Custom command aliases (available everywhere)
alias:
  ll: plugin list --status=active
  tl: theme list --status=active
  flushall: cache flush && rewrite flush
  quickbackup: db export backup-$(date +%Y%m%d).sql.gz

# Default formats
plugin list:
  - --format=table

# Disable auto-check for updates
disable_auto_check_update: true

# Custom package path
packages_dir: ~/.wp-cli/packages/

Personal Aliases

# Useful custom aliases in global config

alias:
  # Quick commands
  status: core is-installed && db check
  info: core version && option get siteurl

  # Maintenance shortcuts
  mm-on: maintenance-mode activate
  mm-off: maintenance-mode deactivate

  # Cleanup operations
  cleanup: |
    post delete $(post list --post_status=trash --format=ids) --force
    transient delete --expired
    cache flush

  # Security checks
  security: |
    core verify-checksums
    plugin verify-checksums --all

  # Quick site backup
  backup: |
    db export backups/db-$(date +%Y%m%d-%H%M%S).sql.gz
    echo "Backup complete"

Environment-Specific Configs

Different configurations for development, staging, and production.

Multi-Environment Setup

# Project structure with environment configs
/var/www/
├── wp-cli.yml              # Base config
├── wp-cli.local.yml        # Development overrides
├── wp-cli.staging.yml      # Staging overrides
└── wp-cli.production.yml   # Production overrides

Base Config (wp-cli.yml)

# wp-cli.yml - Shared across all environments

path: public
color: true

# Commands available in all environments
alias:
  status: core is-installed && db check

Development Config (wp-cli.local.yml)

# wp-cli.local.yml - Development settings

url: http://localhost:8080
debug: true
allow-root: true

# Enable all error output
WP_DEBUG: true
WP_DEBUG_LOG: true
WP_DEBUG_DISPLAY: true

# Development-specific aliases
alias:
  seed: scaffold post-content --count=50
  reset-db: db reset --yes && core install --url=http://localhost:8080 --title="Dev Site" --admin_user=admin --admin_email=dev@example.test

Production Config (wp-cli.production.yml)

# wp-cli.production.yml - Production settings

url: https://example.com
debug: false
quiet: false
allow-root: true

# Disable dangerous commands
disabled_commands:
  - db drop
  - db reset
  - scaffold

# Production-safe aliases
alias:
  deploy: |
    maintenance-mode activate
    plugin update --all
    theme update --all
    core update
    cache flush
    rewrite flush
    maintenance-mode deactivate

Use Environment Configs

# Load specific config with --config flag
wp --config=wp-cli.local.yml plugin list
wp --config=wp-cli.production.yml core update

# Or use WP_CLI_CONFIG_PATH environment variable
export WP_CLI_CONFIG_PATH=wp-cli.staging.yml
wp plugin list

Learn about WordPress environments best practices.

Advanced Configuration Options

Professional config features for complex workflows.

SSH Remote Execution

# Execute commands on remote servers

@staging:
  ssh: user@staging.example.com/var/www/staging
  path: /var/www/staging

@production:
  ssh: user@prod.example.com/var/www/production
  path: /var/www/production

# Usage:
# wp @staging plugin list
# wp @production core update

HTTP Basic Auth

# For sites behind HTTP authentication

http:
  user: admin
  password: secretpassword

Custom PHP Binary

# Use specific PHP version

php: /usr/bin/php8.1

# or with full path
php_bin: /opt/php/8.1/bin/php

Require Specific Packages

# Ensure WP-CLI packages are installed

require:
  - wp-cli/doctor-command
  - wp-cli/profile-command
  - aaemnnosttv/wp-cli-login-command

Disable Commands

# Prevent dangerous commands on production

disabled_commands:
  - db drop
  - db reset
  - site delete
  - scaffold

Command-Specific Defaults

Set default options for frequently used commands.

Plugin Command Defaults

plugin install:
  - --activate

plugin list:
  - --format=table
  - --fields=name,status,version,update

plugin update:
  - --dry-run # Always preview first

Database Defaults

db export:
  - --add-drop-table

db import:
  - --skip-optimization

search-replace:
  - --dry-run
  - --report
  - --precise

Post Defaults

post list:
  - --post_type=post
  - --orderby=date
  - --order=DESC
  - --posts_per_page=25
  - --fields=ID,post_title,post_status,post_date

post create:
  - --post_status=draft
  - --post_author=1

Security and Team Configs

Secure configs for team collaboration.

Secrets in Environment Variables

# Don't hardcode credentials in config files!

# WRONG (insecure)
http:
  user: admin
  password: secretpassword

# RIGHT (use environment variables)
http:
  user: ${WP_CLI_HTTP_USER}
  password: ${WP_CLI_HTTP_PASSWORD}

Set in shell:

export WP_CLI_HTTP_USER="admin"
export WP_CLI_HTTP_PASSWORD="secretpassword"

.gitignore for Config Files

# .gitignore

# Ignore local overrides
wp-cli.local.yml
wp-cli.*.local.yml

# Ignore configs with secrets
wp-cli.secrets.yml

# Keep base configs
!wp-cli.yml
!wp-cli.example.yml

Team Config Template

# wp-cli.example.yml - Template for team

path: public
url: REPLACE_WITH_YOUR_URL
allow-root: true
# Copy this to wp-cli.local.yml and customize
# cp wp-cli.example.yml wp-cli.local.yml

Next Steps

You now have comprehensive WP-CLI config file knowledge for professional workflows.

Recommended Learning Path

Week 1: Basic configs

Create project wp-cli.yml
Set up global config
Test common settings

Week 2: Environment configs

Create dev/staging/prod configs
Set up SSH aliases
Test environment switching

Week 3: Advanced features

Custom command defaults
Team configurations
Security best practices

Week 4: Optimization

Refine configs for workflow
Document team standards
Share configs via Git

Advanced Topics

WP-CLI Package Development – Build custom commands
WP-CLI in CI/CD – Automated testing configs
Multi-Site Configs – Network-wide settings

Get More Resources

Download config templates including:

Project config examples
Environment-specific configs
Team collaboration templates

Join our email course for:

Weekly WP-CLI tutorials
Configuration best practices
Workflow optimization tips

Conclusion

WP-CLI config files transform repetitive command-line work into streamlined, consistent workflows that save time and prevent errors across your entire team.

What we covered:

✅ Config file locations and search order
✅ Project-specific and global configurations
✅ Environment-specific setups (dev/staging/prod)
✅ Advanced options (SSH, custom defaults, aliases)
✅ Command-specific defaults and optimizations
✅ Security and team collaboration practices

Master these configurations, and you’ll never type redundant WP-CLI flags again—just clean, efficient commands that work consistently everywhere.

Ready for more? Learn WP-CLI aliases and shortcuts or custom command development.

Questions about WP-CLI config files? Drop a comment below!

Found this helpful? Share with other WordPress developers.