Simple History includes WP-CLI commands for working with the events log — listing, searching, filtering, and getting database stats, all from the terminal.
Commands overview
The current WP-CLI commands for interacting with the events log are as follows:
wp simple-history event listto list events.wp simple-history listto list events — a shorthand alias ofwp simple-history event list.wp simple-history event getto get details about a single event.wp simple-history event addto add an entry manually.wp simple-history event searchto search events. Deprecated — usewp simple-history event list --searchinstead.wp simple-history db statsto get stats.wp simple-history db clearto clear the events database.wp simple-history event stickto stick an event to the top of the events list.wp simple-history event unstickto unstick an event.wp simple-history event is_stickyto check if an event is sticky.wp simple-history event list_sticky [--format=<format>]to list events that are sticky.
See below for explanation of most of the commands.
WP-CLI event list command
List the latest events.
Filtering Options
The list command supports various filters to narrow down results:
Basic Parameters
| Parameter | Description |
|---|---|
--count=<number> | Number of events to show (default: 10) |
--format=<format> | Output format: table, json, csv, yaml |
--date_from=<date> | Show events from this date (YYYY-MM-DD) |
--date_to=<date> | Show events until this date (YYYY-MM-DD) |
--search=<text> | Search for events containing this text |
--metadata_search=<text> | Search all event metadata/context values (IP addresses, emails, user agents, etc.). Same as the metadata search in the admin interface. |
--ai_only | Show only events initiated via an AI tool (e.g. Claude Code, ChatGPT). Same as the AI filter in the admin interface. |
--fields=<fields> | Comma-separated list of columns to display (default: ID,date,initiator,description,via,level,count) |
Examples of the metadata search and AI filter:
# Search all event metadata for an IP address
wp simple-history event list --metadata_search="192.168.1.100"
# Show only events initiated via an AI tool (e.g. Claude Code, ChatGPT)
wp simple-history event list --ai_only --count=20
# Show full AI attribution: the agent, how it was detected, and the application
wp simple-history event list --ai_only --fields=ID,date,ai_agent,ai_detected_via,ai_application,descriptionCode language: PHP (php)The ai_agent, ai_detected_via, and ai_application columns are only filled in for events initiated via an AI tool — they’ll be empty for everything else.
Inclusion Filters
| Parameter | Description |
|---|---|
--log_level=<levels> | Include only events with these log levels (comma-separated) |
--logger=<loggers> | Include only events from these loggers (comma-separated) |
--message=<messages> | Include only specific message types in format “LoggerSlug:MessageKey” (comma-separated) |
--user=<ids> | Include only events by these user IDs (comma-separated) |
--initiator=<types> | Include only events by these initiators (comma-separated) |
Exclusion Filters (Negative Filters)
Use these parameters to exclude events matching specific criteria:
| Parameter | Description |
|---|---|
--exclude_log_level=<levels> | Exclude events with these log levels (comma-separated) |
--exclude_logger=<loggers> | Exclude events from these loggers (comma-separated) |
--exclude_message=<messages> | Exclude specific message types in format “LoggerSlug:MessageKey” (comma-separated) |
--exclude_user=<ids> | Exclude events by these user IDs (comma-separated) |
--exclude_initiator=<types> | Exclude events by these initiators (comma-separated) |
--exclude_search=<text> | Exclude events containing this text |
Valid Initiator Values
wp_user– Regular WordPress user actionswp_cli– Actions performed via WP-CLIwp– WordPress system actions (cron jobs, automatic updates)web_user– Non-logged-in web visitorsother– Other sources
Exclusion Filter Examples
# View events excluding debug level
wp simple-history event list --exclude_log_level=debug --count=50
# Exclude WordPress system events (cron, auto-updates)
wp simple-history event list --exclude_initiator=wp --count=50
# Exclude events containing "cron"
wp simple-history event list --exclude_search=cron --count=50
# Exclude multiple log levels
wp simple-history event list --exclude_log_level=debug,info --count=50
# Exclude specific message types
wp simple-history event list --exclude_message=SimplePluginLogger:plugin_activated --count=50
# Combine filters: show user events, exclude admin user
wp simple-history event list --initiator=wp_user --exclude_user=1 --count=50
# Show warning/error events only, exclude cron-related
wp simple-history event list --log_level=warning,error --exclude_search=cron --count=50Code language: Bash (bash)Note: When the same value appears in both an inclusion and exclusion filter, exclusion takes precedence.
WP-CLI event get command
The event get command retrieves detailed information about a single event:
❯ wp simple-history event get 1072
+-----------------------------+-------------------------------------------------------------+
| Field | Value |
+-----------------------------+-------------------------------------------------------------+
| ID | 1072 |
| date | 2024-02-26 07:13:19 |
| initiator | WordPress |
| message | WordPress auto-updated to 6.4.3 from 6.4.2 |
| via | null |
| logger | SimpleCoreUpdatesLogger |
| level | notice |
| count | 1 |
| _message_key | core_auto_updated |
| _message | WordPress auto-updated to {new_version} from {prev_version} |
| _initiator | wp |
| context_prev_version | 6.4.2 |
| context_new_version | 6.4.3 |
| context__message_key | core_auto_updated |
| context__wp_cron_running | true |
| context__server_remote_addr | 127.0.0.1 |
+-----------------------------+-------------------------------------------------------------+Code language: plaintext (plaintext)WP-CLI event add command
Add a custom entry manually. This can be used to document important changes by creating custom log entries for team actions, content updates, or system changes that aren’t automatically tracked.
To add events using a GUI you can use the premium add-on.
WP-CLI search command (deprecated)
The event search command is deprecated and will be removed in a future version. Use the --search option on the list command instead — it searches the same way and can be combined with all the other filters:
wp simple-history event list --search=WooCommerceCode language: plaintext (plaintext)WP-CLI db commands
The “stats” and “clear” commands are used to interact with the database.
❯ wp simple-history db
usage: wp simple-history db clear
or: wp simple-history db stats [--format=<table|json|csv|yaml>]Code language: plaintext (plaintext)The “stats” command gives you some short information about the sizes, in mb and in row count, of the databases that Simple History uses:
❯ wp simple-history db stats
+-----------------------------------+------------+----------+
| table_name | size_in_mb | num_rows |
+-----------------------------------+------------+----------+
| wp_stable_simple_history | 0.34 | 1143 |
| wp_stable_simple_history_contexts | 6.20 | 12151 |
+-----------------------------------+------------+----------+The clear command removes all items from the database:
❯ wp simple-history db clear
Are you sure you want to clear all logged items? [y/n] y
Success: Removed 1145 rows.Code language: plaintext (plaintext)