wp user list

Overview

List and query all WordPress users. Filter by role, search by field, format output as table, JSON, or CSV — a key tool for security audits, reporting, and scripting bulk user operations.

What It Does

wp user list queries the wp_users table and outputs configured fields. Every output format is machine-readable for piping into other commands.

Syntax

wp user list [OPTIONS]

Arguments & Options

Flag	Description
--role=ROLE	Filter by role (e.g. administrator, editor)
--fields=FIELDS	Comma-separated fields to display
--field=FIELD	Output a single field value per line (for scripting)
--format=FORMAT	Output format: table (default), json, csv, yaml, ids
--search=PATTERN	Search login, email, URL, name
--orderby=FIELD	Sort by field (e.g. registered, login)
--order=ASC_OR_DESC	Sort direction
--number=N	Max number of users to return
--exclude=IDS	Comma-separated user IDs to exclude

Basic Usage

List all users (default table)

wp user list

List only administrators

wp user list --role=administrator

Custom fields output

wp user list --fields=ID,user_login,user_email,roles --format=table

Get only user IDs (for scripting)

wp user list --role=subscriber --field=ID

Export as JSON

wp user list --format=json > all-users.json

Export as CSV

wp user list --fields=ID,user_login,user_email,roles --format=csv > users-export.csv

Real-World Scenarios

Scenario 1: Security audit — list all admins

wp user list --role=administrator \
  --fields=ID,user_login,user_email,user_registered \
  --format=table

Scenario 2: Find users registered in a date range

wp user list --fields=ID,user_login,user_registered \
  --orderby=registered \
  --order=desc \
  --number=50 \
  --format=table

Scenario 3: Export subscriber list for email tool

wp user list --role=subscriber \
  --fields=user_email,display_name \
  --format=csv > subscribers.csv

Scenario 4: Count users per role

for role in administrator editor author contributor subscriber; do
  COUNT=$(wp user list --role="$role" --field=ID | wc -l)
  echo "$role: $COUNT"
done

Best Practices

1. Use --field=ID in loops instead of --format=ids for wider compatibility.
2. Use --format=json when exporting for downstream processing.
3. Use --number to limit large datasets during testing.
4. Use --fields to only request what you need — speeds up output on large sites.

Quick Reference

wp user list                                        # All users, default table
wp user list --role=administrator                   # Filter by role
wp user list --field=user_login                     # One field per line
wp user list --fields=ID,user_login,user_email,roles --format=csv
wp user list --format=json > users.json

Next Steps

• wp user get — get detailed info for a single user.
• wp user create — create new users.
• wp user delete — remove users.