WP-CLI add-on for Simple JWT Login
Generate JWT tokens and manage plugin configuration directly from the command line.
- WordPress 4.4+
- PHP 5.5+
- Simple JWT Login plugin installed and active
- WP-CLI installed and accessible as
wp
From WordPress.org:
- In your WordPress admin go to Plugins → Add New.
- Search for
Simple JWT Login CLIand click Install Now. - Activate the plugin.
From zip:
- Download the latest release zip.
- Go to Plugins → Add New → Upload Plugin and upload the zip.
- Activate the plugin.
Important
This plugin will automatically deactivate itself if the Simple JWT Login plugin is not active.
Verify the commands are registered:
wp jwt --help
wp jwt config --helpAuthenticate a WordPress user and print a JWT token.
Note
Authentication must be enabled in Admin → Simple JWT Login → Authentication → Allow Authentication.
Synopsis
wp jwt login [--username=<username>] [--email=<email>] [--login=<login>] --password=<password> [--format=<format>]
| Option | Required | Description |
|---|---|---|
--username=<username> |
One of the three identifiers | WordPress username |
--email=<email> |
One of the three identifiers | WordPress user email address |
--login=<login> |
One of the three identifiers | Username or email - tried as username first, then email |
--password=<password> |
Yes | WordPress user password |
--format=<format> |
No | text (default) or json |
Priority when multiple identifiers are supplied: --username > --email > --login.
Examples
# Authenticate by username
wp jwt login --username=admin --password=secret
# Authenticate by email
wp jwt login [email protected] --password=secret
# Authenticate by login (username or email)
wp jwt login --login=admin --password=secret
# JSON output
wp jwt login --username=admin --password=secret --format=json
# {"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
# Capture token into a shell variable
TOKEN=$(wp jwt login --username=admin --password=secret)
curl -H "Authorization: Bearer $TOKEN" https://example.com/wp-json/...Decode the payload of a JWT token and display its claims. The signature is not verified - use wp jwt validate for that.
Synopsis
wp jwt decode <token> [--format=<format>]
| Argument | Required | Description |
|---|---|---|
<token> |
Yes | The JWT token to decode. |
--format=<format> |
No | text (default) or json |
Examples
# Inspect the payload in text format
wp jwt decode eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwiZXhwIjoxOTk5OTk5fQ.sig
# id 1
# exp 1999999
# Get the raw payload as JSON (pipe-friendly)
wp jwt decode eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MX0.sig --format=json
# {"id":1}
# Extract a single claim with jq
TOKEN=$(wp jwt login --username=admin --password=secret)
wp jwt decode "$TOKEN" --format=json | jq '.exp'Validate a JWT token - verifies the signature against the plugin's decryption key and checks that the token has not expired.
Note
The plugin's decryption key and algorithm must be configured (wp jwt config set decryption_key <key>).
Synopsis
wp jwt validate <token> [--format=<format>]
| Argument | Required | Description |
|---|---|---|
<token> |
Yes | The JWT token to validate. |
--format=<format> |
No | text (default) or json |
The command always exits 0 - check the valid field in the output to determine the result.
Examples
# Validate and display result as text
wp jwt validate eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MX0.abc
# valid 1
# message Token is valid.
# Validate and get JSON (useful in scripts)
wp jwt validate "$TOKEN" --format=json
# {"valid":true,"message":"Token is valid."}
# Check validity in a shell script
RESULT=$(wp jwt validate "$TOKEN" --format=json)
if [ "$(echo "$RESULT" | jq -r '.valid')" = "true" ]; then
echo "Token OK"
else
echo "Token invalid: $(echo "$RESULT" | jq -r '.message')"
fiRevoke a JWT token so it can no longer be used for authentication. The token signature is verified before revocation. The token is stored in the user's WordPress meta under the plugin's revoke key.
Note
The plugin's decryption key must be configured and the JWT payload must contain the claim used to identify users (configured in Simple JWT Login → Login → Login by).
Synopsis
wp jwt revoke <token> [--format=<format>]
| Argument | Required | Description |
|---|---|---|
<token> |
Yes | The JWT token to revoke. |
--format=<format> |
No | text (default) or json |
Examples
# Revoke a token
wp jwt revoke eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MX0.abc
# success 1
# message Token has been revoked.
# Revoke and get JSON output
wp jwt revoke "$TOKEN" --format=json
# {"success":true,"message":"Token has been revoked."}
# Log in, then immediately revoke the token
TOKEN=$(wp jwt login --username=admin --password=secret)
wp jwt revoke "$TOKEN"Print the current value of a plugin setting.
wp jwt config get <key> [--format=<format>]
| Argument | Required | Description |
|---|---|---|
<key> |
Yes | Setting key. Use dot notation for nested keys (e.g. cors.enabled). |
--format=<format> |
No | text (default) or json |
wp jwt config get allow_authentication
# 1
wp jwt config get jwt_algorithm
# HS256
wp jwt config get cors.enabled
# 1
wp jwt config get jwt_payload --format=json
# ["iat","exp","id"]Update the value of a plugin setting and save it to the database.
wp jwt config set <key> <value> [--type=<type>] [--force]
| Argument | Required | Description |
|---|---|---|
<key> |
Yes | Setting key, with dot notation for nested keys. |
<value> |
Yes | New value. |
--type=<type> |
No | auto (default), string, int, bool, or json |
--force |
No | Skip plugin validation and save regardless of validation errors. |
With --type=auto the type is inferred from the currently stored value. A stored boolean stays a boolean, an integer stays an integer, an array expects a JSON string. When no value is stored yet, the raw string is saved as-is.
# Enable authentication
wp jwt config set allow_authentication 1
# Change the JWT algorithm
wp jwt config set jwt_algorithm RS256
# Enable CORS
wp jwt config set cors.enabled true
# Set JWT TTL to 2 hours (explicit int)
wp jwt config set jwt_auth_ttl 7200 --type=int
# Set the decryption key
wp jwt config set decryption_key "my-super-secret"
# Replace JWT payload fields (JSON array)
wp jwt config set jwt_payload '["iat","exp","id","email"]' --type=jsonShow all stored settings as a flat key/value table or as raw JSON.
wp jwt config list [--format=<format>]
| Option | Description |
|---|---|
--format=text |
Default. One key value line per setting; nested objects expanded with dot notation. |
--format=json |
Full settings object as pretty-printed JSON. |
wp jwt config list
# allow_authentication 1
# jwt_algorithm HS256
# cors.enabled 1
# ...
wp jwt config list --format=jsonExport the full plugin configuration as JSON to a file or stdout.
wp jwt config export [--file=<path>]
# Print to stdout
wp jwt config export
# Save to a file
wp jwt config export --file=jwt-config.json
# Filter with jq
wp jwt config export | jq '.jwt_algorithm'Import plugin configuration from a JSON file produced by wp jwt config export.
By default the entire settings object is replaced. Use --merge to update only the keys present in the file.
Before saving, the command shows a diff of every change and asks for confirmation unless --yes is passed.
wp jwt config import <file> [--merge] [--dry-run] [--yes] [--force]
| Option | Description |
|---|---|
<file> |
Path to the JSON file to import. |
--merge |
Merge into existing settings instead of replacing them. |
--dry-run |
Show what would change without saving anything. |
--yes |
Skip the confirmation prompt (for scripts/CI). |
--force |
Skip plugin validation and save regardless of validation errors. |
# Full replace with confirmation prompt
wp jwt config import jwt-config.json
# Preview changes without saving
wp jwt config import jwt-config.json --dry-run
# Merge partial settings
wp jwt config import partial.json --merge
# Non-interactive (CI)
wp jwt config import jwt-config.json --yesBackup / restore workflow:
# On source site
wp jwt config export --file=jwt-config.json
# On target site
wp jwt config import jwt-config.json --yes| Error | Cause | Fix |
|---|---|---|
Authentication is not enabled. |
Authentication section is disabled | wp jwt config set allow_authentication 1 |
Wrong user credentials. |
Incorrect username/email or password | Double-check the credentials |
Please provide --username, --email, or --login |
No identifier flag was passed | Add --username, --email, or --login |
Please provide --password |
--password flag is missing |
Add --password |
Invalid format. Accepted values: text, json |
Unsupported --format value |
Use --format=text or --format=json |
Could not decode token. Ensure it has a valid JWT structure … |
Token is not a valid JWT (not three dot-separated parts) | Check that you are passing the full token |
Token is valid. / valid: false |
wp jwt validate result |
A false result includes a message explaining why (expired, bad signature, etc.) |
Token has been revoked. |
wp jwt revoke success |
The token is now blocked from being used |
Token has already been revoked. |
Attempting to revoke the same token twice | The token was previously revoked; no action needed |
User not found. (revoke) |
JWT payload user identifier does not match any WP user | Ensure the token was issued for an existing user |
JWT payload does not contain the "<claim>" claim. |
The login-by claim is absent from the payload | Re-issue the token or change the Login by setting in Simple JWT Login |
Setting "<key>" not found. |
Key has no stored value | Setting uses plugin default; use set to store an explicit value |
The current value is an array. … |
Trying to set an array key without --type=json |
Add --type=json and pass a JSON array/object |
Invalid JSON value: … |
Malformed JSON passed with --type=json |
Validate your JSON before passing it |
Cannot read file: <path> |
File does not exist or is not readable | Check the path and file permissions |
Invalid JSON in <file>: … |
Import file is not valid JSON | Validate with jq . <file> before importing |
No changes detected. |
Import file matches stored settings | Nothing to do; settings are already up-to-date |
| Plugin auto-deactivated | Simple JWT Login is not active | Install and activate Simple JWT Login first |
Contributions are welcome! Please open an issue to discuss any change before submitting a pull request.
- Clone the main simple-jwt-login-cli repository.
git clone https://github.com/simple-jwt-login/simple-jwt-login-cli.git- Start the Docker environment:
docker compose -f docker-compose.yaml up
- Connect to the container:
docker exec -it simple-jwt-login-cli-wpcli-1 /bin/bash cd /var/www/html/wp-content/plugins/simple-jwt-login-cli/ composer install
- Run tests:
composer run tests
- Run the full quality suite before submitting:
composer run check-plugin
Please follow the Code of Conduct.