WP-CLI commands

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 list to list events.
• wp simple-history list to list events — a shorthand alias of wp simple-history event list.
• wp simple-history event get to get details about a single event.
• wp simple-history event add to add an entry manually.
• wp simple-history event search to search events. Deprecated — use wp simple-history event list --search instead.
• wp simple-history db stats to get stats.
• wp simple-history db clear to clear the events database.
• wp simple-history event stick to stick an event to the top of the events list.
• wp simple-history event unstick to unstick an event.
• wp simple-history event is_sticky to check if an event is sticky.
• wp simple-history event list_sticky [--format=<format>] to list events that are sticky.
• wp simple-history info to show the Simple History version, whether the premium add-on is active, and useful links.

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. Accepts YYYY-MM-DD, YYYY-MM-DD HH:MM:SS or a Unix timestamp.
--date_to=<date>	Show events up to this date. Same formats as --date_from.
--months=<months>	Show events from these months, in YYYY-MM format (comma-separated)
--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.
--orderby=<column>	Column to sort by: date (default), id, level, logger or message (the event type). See Sorting.
--order=<direction>	Sort direction: desc (default, newest first) or asc
--include_sticky	Include sticky events in the results
--only_sticky	Show only sticky events
--fields=<fields>	Comma-separated list of columns to display (default: ID,date,initiator,description,via,level,count). See Columns for all available columns.

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)
--userid=<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_userid=<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 actions
• wp_cli – Actions performed via WP-CLI
• wp – WordPress system actions (cron jobs, automatic updates)
• web_user – Non-logged-in web visitors
• other – 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_userid=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.

Filtering by user: use --userid and --exclude_userid. Don’t use --user: that is a global WP-CLI parameter that sets which user runs the command, so it doesn’t filter anything.

Sorting

By default the newest events come first. Use --orderby and --order to sort by something else. Sorting by level orders by severity, so with --order=desc the most serious events come first.

# Show the oldest events first
wp simple-history event list --orderby=date --order=asc

# Show the first logged events, by event ID
wp simple-history event list --orderby=id --order=asc

# Most serious events first
wp simple-history event list --orderby=level --order=desc --count=50

# Sort by logger, then filter to one month
wp simple-history event list --orderby=logger --order=asc --months=2026-09Code language: Bash (bash)

--orderby=id and --orderby=date usually give the same order. They can differ for events that were imported or backfilled, since those get a new ID but keep their original date.

Surrounding events

Show what happened just before and after a specific event. Handy when debugging, to see the full picture around one event. This requires administrator privileges, and it shows events from all loggers, including ones the logger permissions would normally hide.

Parameter	Description
--surrounding_event_id=<id>	Show the events before and after this event ID
--surrounding_count=<number>	How many events to show before and after the event (default: 5)

# Show 5 events before and 5 after event 123 (11 events in total)
wp simple-history event list --surrounding_event_id=123

# Show 10 events before and after event 456
wp simple-history event list --surrounding_event_id=456 --surrounding_count=10Code language: Bash (bash)

Columns

Pick the columns to show with --fields. Available columns: ID, date, date_relative, initiator, logger, level, who_when, description, via, count, reactions, site, ai_agent, ai_detected_via and ai_application.

# Relative dates ("5 minutes ago") for easier scanning
wp simple-history event list --fields=ID,date_relative,initiator,description

# Show which logger wrote each event
wp simple-history event list --fields=ID,date,logger,description

# Show events with reactions
wp simple-history event list --fields=ID,date,description,reactions

# On multisite: include the site name
wp simple-history event list --fields=ID,date,site,descriptionCode language: Bash (bash)

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)