Skip to main content

User Listing & Authentication

Overview

Reliable operations start with visibility and access control. WP-CLI lets you list users with precise filters and authenticate safely for local, remote, and multisite administration.

Why This Topic Matters​

You use listing and authentication commands to:

  • Audit accounts quickly (admins, editors, inactive users)
  • Export user data for reporting and automation
  • Validate identity and permissions before sensitive changes
  • Operate remote environments over SSH or HTTP

User Listing Fundamentals​

List All Users with Key Fields​

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

Filter by Role​

wp user list --role=administrator --fields=ID,user_login,user_email --format=table
wp user list --role=editor --field=user_login

Output Formats for Automation​

# JSON for scripts
wp user list --role=subscriber --format=json

# CSV for spreadsheets
wp user list --fields=ID,user_login,user_email,roles --format=csv > users.csv

# Count for quick checks
wp user list --role=administrator --format=count

Inspect One User in Detail​

# Full record
wp user get john

# Single field
wp user get john --field=roles
wp user get john --field=user_email

Authentication Approaches​

1) Local Authentication (Current WordPress Context)​

WP-CLI runs as the OS user on the machine. Ensure you are in the right WordPress path before running user commands.

wp option get siteurl
wp core is-installed
# Run user list on remote host over SSH
wp --ssh=deploy@server.example.com:/var/www/html user list --role=administrator

3) HTTP Authentication (When SSH Is Not Available)​

# Use HTTPS and app credentials
wp --http=https://example.com --user=admin --prompt=user_pass user list
Safer Credentials

Prefer SSH keys for remote CLI. If using HTTP auth, avoid passing passwords directly in shell history; use --prompt or environment variables.

Role and Access Audits​

Admin Account Audit​

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

Detect Suspicious Naming Patterns​

wp user list --field=user_login | grep -E 'admin|test|backup|temp'

Verify a User Exists Before Changes​

if wp user get editor1 --field=ID > /dev/null 2>&1; then
  echo "User exists"
else
  echo "User not found"
fi

Multisite Listing Patterns​

List Network Sites​

wp site list --fields=blog_id,url --format=table

Audit Admins Across All Sites​

#!/bin/bash
# multisite-admin-audit.sh

for url in $(wp site list --field=url); do
  echo "=== $url ==="
  wp --url="$url" user list --role=administrator --fields=user_login,user_email --format=table
done

Real-World Scenarios​

Scenario 1: Weekly Privileged-User Report​

#!/bin/bash
# weekly-admin-report.sh

DATE=$(date +%Y-%m-%d)
wp user list --role=administrator \
  --fields=ID,user_login,user_email,user_registered \
  --format=csv > "admin-report-$DATE.csv"

Scenario 2: Pre-Migration User Export​

wp user list --fields=ID,user_login,user_email,roles,user_registered --format=json > users-pre-migration.json

Scenario 3: Remote Audit via SSH​

wp --ssh=ops@prod.example.com:/var/www/html user list --role=administrator --fields=user_login,user_email --format=table

Scenario 4: Investigate an Account Quickly​

wp user get suspect-user --fields=ID,user_email,roles,user_registered,display_name
wp user meta list suspect-user

Best Practices​

1. Minimize Data Exposure​

Request only fields you need:

wp user list --fields=ID,user_login,roles

2. Prefer SSH Keys Over Password Auth​

Use key-based auth with restricted users for audit scripts and automation.

3. Use Structured Output in Pipelines​

wp user list --format=json | jq '.[] | {login: .user_login, roles: .roles}'

4. Scope Correctly in Multisite​

wp --url=site2.example.com user list --role=editor

5. Keep an Audit Trail​

Save command outputs for governance and incident reviews.

Troubleshooting​

Authentication Fails Over SSH​

# Test SSH connectivity first
ssh deploy@server.example.com

# Then run a simple remote WP-CLI command
wp --ssh=deploy@server.example.com:/var/www/html core is-installed

HTTP Auth Fails​

# Verify site URL and SSL
wp --http=https://example.com option get siteurl

Check credentials, HTTPS certs, and whether the endpoint supports your command.

Empty or Unexpected List Results​

# Confirm context and table prefix are correct
wp option get siteurl
wp db prefix

Quick Reference​

# Core listing
wp user list --fields=ID,user_login,user_email,roles --format=table
wp user list --role=administrator --format=count
wp user get <user>

# Export
wp user list --format=json > users.json
wp user list --format=csv > users.csv

# Remote authentication
wp --ssh=<user>@<host>:<path> user list
wp --http=<url> --user=<username> --prompt=user_pass user list

# Multisite
wp site list --field=url
wp --url=<site-url> user list --role=administrator

Comparison: WP-CLI vs wp-admin for Audits​

TaskWP-CLIwp-admin
Export all usersOne command (json/csv)Manual or plugin-dependent
Count adminsInstant (--format=count)Manual filtering
Remote checksSSH/HTTP-nativeBrowser login per site
Multisite-wide auditScriptable loopTime-consuming
Key Takeaway

WP-CLI gives faster visibility, safer automation, and better repeatability for user audits and authenticated remote operations.

Next Steps​