Getting Started

Minimal Steps

Verify WP-CLI Access: Ensure you have WP-CLI installed and can access your WordPress multisite installation:
```
wp --info
```
Confirm wp-cli/super-admin-command is listed under "Installed Packages."
Check Multisite Status: Run:
```
wp option get blog_id
```
A value greater than 1 confirms a multisite setup.
First Command: List existing super admins:
```
wp super-admin list
```
Outputs a list of usernames with super-admin privileges.

Where to Look First

Command Reference: Run wp help super-admin for syntax and options.
Output Formats: Use --format=<format> (e.g., --format=json) for programmatic use:
```
wp super-admin list --format=json
```
User Identification: Accepts user IDs, emails, or logins (e.g., wp super-admin add user@example.com).

First Use Case

Automate Onboarding: Grant super-admin access to a new team member during deployment:

wp super-admin add new_team_member@example.com

Verify:

wp super-admin list --format=table

Implementation Patterns

Core Workflows

Bulk Operations: Add multiple users in a single command:

wp super-admin add user1@example.com user2@example.com

Remove users by ID or login:

wp super-admin remove 123 456

Integration with Scripts: Use --format=json for programmatic parsing:

wp super-admin list --format=json | jq '.users[] | select(.id == 1)'

Example: Filter super admins in a Bash script:

SUPER_ADMINS=$(wp super-admin list --format=ids)
for ID in $SUPER_ADMINS; do
    echo "User $ID has super-admin access"
done

CI/CD Pipelines: Automate super-admin assignment during site provisioning (e.g., GitHub Actions):
```
- name: Grant super-admin
  run: wp super-admin add deploy-bot@example.com
```

Laravel-Specific Patterns

WP-CLI in Laravel Artisan: Use wp-cli/wp-cli-bundle to integrate WP-CLI with Laravel:

composer require wp-cli/wp-cli-bundle

Configure in config/wp-cli.php:

'commands' => [
    'super-admin' => [
        'list' => 'wp super-admin list --format=json',
        'add' => 'wp super-admin add {user}',
    ],
],

Call from Laravel:

$superAdmins = Artisan::call('wp:super-admin:list');
$output = json_decode($superAdmins->output(), true);

Dynamic User Management: Sync Laravel users with WordPress super admins:

public function syncSuperAdmins()
{
    $laravelAdmins = User::where('role', 'admin')->pluck('email');
    foreach ($laravelAdmins as $email) {
        Artisan::call('wp:super-admin:add', ['user' => $email]);
    }
}

Event-Driven Workflows: Trigger super-admin changes on Laravel events (e.g., user registration):

UserRegistered::dispatch(function ($user) {
    if ($user->is_team_lead) {
        Artisan::call('wp:super-admin:add', ['user' => $user->email]);
    }
});

Integration Tips

Error Handling: Check exit codes in scripts:

wp super-admin add invalid_user@example.com || echo "Failed to add user"

Dry Runs: Test changes without applying them (use --dry-run if supported by future updates).

Logging: Redirect output to a file for auditing:

wp super-admin list --format=json > super_admins.json

Gotchas and Tips

Pitfalls

Multisite Requirement:
- Error: wp super-admin list returns no output on single-site installs.
- Fix: Verify multisite with wp option get blog_id. Use --network flag if needed (though not natively supported; check WP-CLI version).
User Ambiguity:
- Error: wp super-admin add user@example.com fails if multiple users share the email.
- Fix: Use --user-id or --user-login for precision:
```
wp super-admin add --user-id=123
```
Permissions:
- Error: Non-super-admin users cannot add/remove super admins.
- Fix: Run commands as a super admin or use wp user login to switch roles temporarily.
Output Parsing:
- Error: --format=json may include metadata not documented.
- Fix: Inspect raw output:
```
wp super-admin list --format=json | jq
```

Debugging

Verbose Mode: Enable debug output for troubleshooting:
```
WP_CLI_DEBUG=1 wp super-admin add user@example.com
```
Check WP-CLI Version: Ensure compatibility with wp --version. Update if using an old version:
```
wp package update wp-cli/super-admin-command
```
Database Locks:
- Symptom: Commands hang or timeout.
- Fix: Avoid concurrent operations. Use wp db optimize if locks persist.

Configuration Quirks

Default Formats:
- --format=ids outputs raw IDs (e.g., 1 2 3), not JSON arrays.
- Workaround: Parse as a string and split:
```
IFS=' ' read -ra ADMINS <<< "$(wp super-admin list --format=ids)"
```
Case Sensitivity: User logins are case-sensitive in WordPress. Ensure exact matches:
```
wp super-admin add AdminUser  # Fails if user is "adminuser"
```

Extension Points

Custom Commands: Extend functionality by creating a custom WP-CLI command:

// bootstrap.php
WP_CLI::add_command('custom-super-admin', 'CustomSuperAdminCommand');
class CustomSuperAdminCommand extends \WP_CLI_Command {
    public function __invoke($args, $assoc_args) {
        $superAdmins = \WP_CLI::runcommand('super-admin list --format=json');
        // Custom logic here
    }
}

Hooks: Trigger actions when super-admin roles change (requires custom code):

add_action('wpcli_super_admin_add', function($user_id) {
    // Log or notify when a user gains super-admin access
});

Pre/Post Commands: Use wp-cli/wp-cli-bundle to wrap commands with Laravel logic:

// app/Console/Commands/WpSuperAdmin.php
protected function handle()
{
    $output = Artisan::call('wp:super-admin:list', ['--format' => 'json']);
    $this->logSuperAdmins(json_decode($output->output(), true));
}

Pro Tips

Backup First: Always back up the wp_usermeta table before bulk operations:
```
wp db export --tables=wp_usermeta backup.sql
```

Audit Trails: Combine with wp user log to track changes:

wp super-admin add user@example.com && wp user log --user=user@example.com

Performance: For large multisites, use --batch (if supported in future updates) to reduce memory usage:
```
wp super-admin list --batch=50
```

Local Development: Test changes in a local multisite environment:

wp scaffold multisite --title="Test Network" --slug="test" --admin_user=admin --admin_password=password

Super Admin Command Laravel Package