Configuration Files

Overview

Manage wp-config.php programmatically with WP-CLI to standardize installs, enforce security controls, and automate environment configuration.

Understanding Configuration Files

WP-CLI configuration commands (wp config ...) let you create and manage wp-config.php without manual editing. This enables repeatable installs, consistent deployments, and safer security operations.

Who This Is For

• Developers → Automate project setups.
• Sysadmins → Deploy sites at scale.
• Agencies → Standardize config creation across clients.
• Security-conscious users → Quickly rotate salts/keys.

Where You'll Use It

• In the WordPress root directory (/var/www/html/).
• On local machines (dev setup) and remote servers (deployments).

When You'll Use Config Commands

• During initial installation of WordPress.
• When migrating sites between servers.
• To change DB credentials or prefix for security.
• To rotate authentication salts/keys.

Why Config Automation Matters

• Automate config creation (no manual edits).
• Improve security (salts, DB prefix).
• Ensure consistency across environments.
• Enable faster deployments.

Command Shape and Subcommands

• Syntax pattern:

wp config <subcommand> [--options]

• Main subcommands:
  • create → Generate new wp-config.php.
  • list → Show constants/variables.
  • set → Add/update constants/variables.
  • delete → Remove constants/variables.
  • shuffle-salts → Regenerate keys/salts.

Secrets and Version Control

wp-config.php usually contains secrets. Never commit it to version control and prefer environment variables or secret managers for sensitive values.

Prerequisites and Preparation

Required Tools

• WP-CLI installed.
• Database ready (MySQL/MariaDB).
• PHP CLI available.

Preparation

1. Confirm DB exists:

mysql -u root -p -e "CREATE DATABASE mydb;"

2. Collect DB credentials: dbname, dbuser, dbpass, dbhost.
3. Navigate to WordPress root directory.

Configuration Command Reference

Quick Command Matrix

Subcommand	Syntax	Options / Flags	Purpose
Create	wp config create --dbname=NAME --dbuser=USER --dbpass=PASS [--dbhost=HOST] [--dbprefix=PREFIX] [--skip-check] [--extra-php]	--skip-check → skip DB connection check, --extra-php → add custom PHP code	Generate new wp-config.php
List	wp config list [--format=FORMAT]	--format=table/json/csv/yaml	List all constants & variables
Set	wp config set [--raw] [--type=CONSTANT_OR_VARIABLE]	--raw → store value without quotes
Delete	wp config delete [--type=CONSTANT_OR_VARIABLE]	None
Shuffle-Salts	wp config shuffle-salts	None	Regenerate authentication keys/salts

Configuration Commands in Practice

Create a Config File (wp config create)

wp config create --dbname=wpdb --dbuser=wpuser --dbpass=secret --dbhost=localhost --dbprefix=wp_

Use this to generate a valid wp-config.php without manual editing.

Skip DB Connection Check (Bootstrap Only)

wp config create --dbname=wpdb --dbuser=wpuser --dbpass=secret --skip-check

When to use --skip-check

Use --skip-check only when the database is intentionally not reachable yet (for example, during early provisioning). Validate connectivity before you run install and application commands.

Inspect Configuration (wp config list)

wp config list --format=table

Set and Delete Constants (wp config set, wp config delete)

wp config set WP_DEBUG true --raw
wp config delete WP_DEBUG

Rotate Authentication Salts (wp config shuffle-salts)

wp config shuffle-salts

Add Extra PHP During Creation (--extra-php)

wp config create --dbname=wpdb --dbuser=wpuser --dbpass=secret --extra-php <<PHP
define( 'WP_DEBUG_LOG', true );
define( 'WP_MEMORY_LIMIT', '256M' );
PHP

Treat --extra-php as code

Anything added via --extra-php executes in WordPress runtime. Keep it minimal, review it, and avoid inserting secrets.

Benefits

Benefit	Explanation	Impact
Automation	Create configs without manual edits	Faster setups
Security	Rotate salts, change DB prefix	Stronger defense
Consistency	Standardize configs across sites	Predictable deployments
Flexibility	Add custom constants (debug, cache)	Custom workflows
Recovery	Quickly fix broken configs	Saves downtime

Real-World Scenarios

Scenario 1: Create a Config File

wp config create --dbname=wpdb --dbuser=wpuser --dbpass=secret --dbhost=localhost --dbprefix=wp_

• Use Case: Fresh WordPress installation with specific DB details.

Scenario 2: Skip DB Connection Check

wp config create --dbname=wpdb --dbuser=wpuser --dbpass=secret --skip-check

• Use Case: Staging environment where DB isn’t ready yet.

Scenario 3: Add WP_DEBUG

wp config set WP_DEBUG true --raw

• Use Case: Enable debug mode during development.

Scenario 4: Delete a Constant

wp config delete WP_DEBUG

• Use Case: Disable debug mode in production.

Scenario 5: Regenerate Authentication Salts

wp config shuffle-salts

• Use Case: Security hardening, invalidate all sessions.

Scenario 6: List Config Values

wp config list --format=table

• Use Case: Audit current wp-config values.

Scenario 7: Add Extra PHP During Creation

wp config create --dbname=wpdb --dbuser=wpuser --dbpass=secret --extra-php <<PHP
define( 'WP_DEBUG_LOG', true );
define( 'WP_MEMORY_LIMIT', '256M' );
PHP

• Use Case: Add advanced constants at creation time.

Best Practices

1. Always use strong DB credentials.
2. Use non-default DB prefix (not wp_).
3. Regularly run wp config shuffle-salts.
4. Never commit wp-config.php with secrets into version control.
5. Consider environment variables for secrets ($_ENV or .env integration).
6. Validate changes with wp config list before promoting between environments.
7. Prefer --raw for boolean and numeric constants to avoid quoting mistakes.

Troubleshooting

wp config create Fails the Connection Check

Confirm the database exists and credentials are correct. If you are bootstrapping a staging environment where the DB is not ready yet, use --skip-check and validate later.

wp config set Produces Unexpected Quoting

Use --raw for booleans and numbers:

wp config set WP_DEBUG true --raw

wp-config.php Is Not Updated

This is usually a permissions issue. Ensure WP-CLI can write to the WordPress root directory and that the host has not locked the file.

Quick Reference

Quick Commands

# Create wp-config.php
wp config create --dbname=wpdb --dbuser=wpuser --dbpass=secret --dbhost=localhost --dbprefix=custom_

# List config values
wp config list --format=table

# Add or update constant
wp config set WP_DEBUG true --raw
wp config set WP_MEMORY_LIMIT 256M --raw

# Delete constant
wp config delete WP_DEBUG

# Regenerate salts
wp config shuffle-salts

Comparison: Managing WordPress Configuration

Approach	Best For	Pros	Cons
WP-CLI (wp config ...)	Repeatable installs and automation	Scriptable, consistent, fast	Requires CLI access and correct permissions
Manual editing	One-off hotfixes	Direct and flexible	Error-prone; hard to standardize
Environment-driven config	Modern deployments	Secrets stay out of repo; clear separation per env	Requires runtime support and discipline

Key Takeaway

Use wp config commands to keep configuration changes repeatable, auditable, and safer to automate.

Next Steps

• Continue to Plugin Installation & Updates to automate post-install setup.
• Review Global Parameters to scope config changes to the correct site.
• Review Site Health and Debugging for production incident handling.