Matomo Console Command Reference

Displays help information for a Matomo console command.

./console command:name --help

• Helpful when checking syntax, arguments, and available options.
• Does not modify Matomo data or configuration.

Lists all console commands available on your Matomo instance.

./console list

• Use to discover commands installed by Matomo core and plugins.
• Does not modify Matomo data or configuration.
• Plugin commands may vary depending on your installed plugins.

Generates a shell completion script for Matomo console commands.

./console completion

• Helps improve command discovery in supported shells.
• Does not modify Matomo data or configuration.
• Typically used by administrators who work frequently in the terminal.

Count the number of available commands

## Linux/macOS > ./console list | wc

## Windows > php console list | Measure-Object

## Linux/macOS > ./console list | grep -i core

## Windows > php console list | Select-String -Pattern "core"

Runs the Matomo CLI archiver to process reports and generate archived data.
This command is designed to run automatically through cron jobs or scheduled tasks.

./console core:archive --force-idsites=1 --force-periods=day --force-date-range=2025-06-20,2025-06-20 --max-archives-to-process=1 --concurrent-requests-per-website=1 --concurrent-archivers=1

• Suitable for unattended execution.
• Does not normally prompt for confirmation.
• Large date ranges can increase database load.
• Use concurrency options carefully on smaller servers.

Invalidates archived report data for selected sites, periods, and date ranges so reports can be reprocessed from raw logs.

./console core:invalidate-report-data --dates=2025-11-01,2025-11-06 --sites=1 --periods=day

This example invalidates daily archived reports for site ID 1 between 2025-11-01 and 2025-11-06. Matomo will regenerate these reports during the next archiving run.

• Large invalidation ranges can significantly increase archive processing time and database load.
• Reports are regenerated during the next archiving process.
• Safe for unattended execution.

Clears Matomo caches, including generated assets and temporary cached data.
This command is commonly used after updating Matomo files manually, enabling or disabling plugins, or troubleshooting unexpected behaviour.

du -sh ./tmp

./console core:clear-caches

du -sh ./tmp

This example measures the size of the tmp directory before and after clearing caches.
It helps confirm that cached files were removed and estimates how much temporary storage they were using.

• Safe to run on production systems.
• Does not remove historical analytics data.
• Cache rebuilding may temporarily increase response times.

Permanently deletes historical raw log data, including visits, actions,
and conversions, according to configured retention policies.

• Commonly used for GDPR compliance and database size management.
• Deleting raw logs may limit future report reprocessing capabilities.
• Recommended during low traffic periods on large environments.

Removes outdated or invalid archived reports from archive tables as part of
regular maintenance routines.

• Can reduce archive table growth.
• May improve database performance.
• Safe for recurring maintenance automation.

Removes corrupted or incomplete archive data from Matomo archive tables. If you suspect archive data is broken or incomplete, first check the current archiving status and recent archive runs.

./console diagnostics:archiving-status

If reports need to be rebuilt, invalidate the affected date range so Matomo can reprocess the reports during the next archiving run.

./console core:invalidate-report-data --dates=YYYY-MM-DD,YYYY-MM-DD

You can then run archiving manually or wait for the next scheduled archiving process.

• Typically used when archive integrity problems are suspected.
• May reduce archive table size.
• Run manually during troubleshooting or maintenance.

Checks for missing recommended security files and creates them where possible. Commonly used after installation, migrations, or server configuration changes where permissions may have prevented Matomo from creating security files automatically.

./console core:create-security-files

• Typically run once after installation or migration.
• Safe to re-run after permission or configuration changes.
• Does not modify analytics data.

Removes duplicate entries from the log action table and repairs related database references.

• Can take a long time to complete on large databases.
• Recommended during maintenance windows for high-traffic environments.
• Primarily used for troubleshooting database consistency issues.

Calculates the pages-before-conversion metric for historical conversions.

./console core:calculate-conversion-pages

• Useful when historical conversion data needs this metric calculated.
• May take time on larger Matomo instances.
• Recommended during low traffic periods or maintenance windows.

Manually verify that Matomo can send email using the current email configuration.

./console core:test-email

• Used after configuring SMTP or troubleshooting email delivery.
• Does not modify analytics data.
• Typically run manually during configuration checks.

Runs Matomo system and database upgrades after core or plugin files have been updated.

./console core:update --yes --no-interaction

• Use --yes to confirm the upgrade without prompting.
• Use --no-interaction for unattended execution.
• Back up files and the database before running upgrades.
• Recommended during a maintenance window.

Displays the current Matomo version information. See the changelog for the latest Matomo releases.

./console core:version

• For support, troubleshooting, and upgrade verification.
• Does not modify Matomo data or configuration.
• Safe to run at any time.

Runs Matomo scheduled tasks directly without executing the full
core:archive process.

./console scheduled-tasks:run

This command may also appear as core:run-scheduled-tasks
depending on the Matomo version. Used to test scheduled jobs, force periodic tasks to run immediately, or troubleshoot automation-related functionality.

• Matomo normally executes scheduled tasks automatically during archiving.
• Use when you want to run scheduled tasks independently from report archiving.
• Safe for unattended execution.

Analyses Matomo archive tables and displays human-readable archive information.

• Helpful with troubleshooting archive table growth or archive integrity issues.
• Can identify unexpected archive behaviour or stale archive data.
• Safe for unattended execution.

Displays configuration settings that affect Matomo archiving performance.

• Helpful with troubleshooting archiving performance or concurrency issues.
• Combines relevant configuration values into a single diagnostic view.
• Safe to run on production systems.

Displays environment statistics that may affect Matomo archiving performance.

• Assists with evaluating archive scalability and resource usage.
• Helps identify performance bottlenecks in large environments.
• Safe for unattended execution.

Displays metrics describing the current Matomo archiving status.

• Useful for monitoring archiving activity and processing behaviour.
• Can identify slow or stalled archiving processes.
• Safe to use in automation and monitoring workflows.

Displays the current archive invalidation queue.

• For troubleshooting delayed or stuck archive processing.
• Shows which archives are waiting to be reprocessed.
• Safe for unattended execution.

Displays the current Matomo archiving status, including invalidated archives,
recent archive runs, and active archiving configuration values.

./console diagnostics:archiving-status

The configuration output combines values from the global configuration
and local config.ini.php overrides into a single view.

• Used for troubleshooting archive processing issues.
• Provides a consolidated operational overview of Matomo archiving.
• Safe to run on production systems.

Runs a full diagnostics check to verify Matomo is installed and functioning correctly.

./console diagnostics:run

This command provides a health report similar to the System Check page available in the Matomo interface: Administration > Diagnostic > System Check.

• Suitable for automation, remote server checks, and troubleshooting.
• Can identify missing PHP extensions, permission issues, and configuration problems.
• Safe for unattended execution and monitoring workflows.

Displays unexpected files found in the Matomo installation and optionally deletes them.

• Useful after upgrades, migrations, or manual file operations.
• Can help identify leftover or potentially suspicious files.
• Review results carefully before deleting files automatically.

Displays and follows Matomo log file output in real time.

./console log:watch

• Used when troubleshooting live application issues or background processes.
• Continuously streams new log entries until manually stopped.
• Not supported on Windows environments.

Deletes a configuration setting> from the Matomo configuration.

./console config:delete General trusted_hosts[]

• Removes obsolete or incorrect configuration values.
• Configuration changes may affect tracking, reporting, or system behaviour.
• Recommended to back up configuration files before making changes.

Retrieves a configuration value or section from the Matomo configuration.

./console config:get General

• For troubleshooting configuration issues or validating deployment settings.
• Safe for unattended execution and automation workflows.
• Does not modify configuration values.

Updates configuration settings in config.ini.php.

./console config:set General enable_browser_archiving = 0

• Used for deployment automation and configuration management workflows.
• Incorrect configuration changes may affect system behaviour or performance.
• Recommended to validate changes before applying them in production environments.

Deletes a feature flag from the Matomo feature flag configuration.

./console featureflags:delete example-feature

• For cleaning up deprecated or temporary feature flags.
• Deleting a feature flag may change application behaviour.
• Recommended to verify feature dependencies before removal.

Disables a Matomo feature flag.

./console featureflags:disable example-feature

• For testing, staged rollouts, or temporarily disabling functionality.
• Feature availability may change immediately after disabling the flag.
• Safe for unattended execution.

Enables a Matomo feature flag.

./console featureflags:enable example-feature

• For enabling experimental or staged functionality.
• Feature availability may change immediately after enabling the flag.
• Recommended to test feature behaviour before enabling in production environments.

Anonymises stored raw log data for privacy, compliance, and data retention workflows.

./console privacymanager:anonymize-some-raw-data --no-interaction

• Supports GDPR and privacy compliance workflows.
• Can be executed through cron jobs or scheduled automation.
• Anonymised data cannot be restored automatically.
• Recommended to review retention and anonymisation policies before execution.

Runs OPTIMIZE TABLE on Matomo archive tables to reclaim unused space
and reduce database fragmentation.

./console database:optimize-archive-tables 2025-01-01

This command optimises the archive tables associated with the specified date.
Under the hood, Matomo runs OPTIMIZE TABLE on the relevant archive tables.

• Helps reclaim space from deleted or invalidated archives.
• Can reduce archive table fragmentation and improve database performance.
• Recommended approximately once per month on production environments.
• Avoid running during periods of heavy database activity.

Removes all blocked IP addresses from the Matomo login protection system.

./console login:unblock-blocked-ips

• Helps administrators or users who become locked out after repeated failed login attempts.
• Safe to run on production systems.
• Typically used manually during troubleshooting or account recovery workflows.

Disables two-factor authentication for a specified Matomo user account.

./console twofactorauth:disable-2fa-for-user --login=username

• Useful when a user loses access to their authenticator device or recovery codes.
• Disabling two-factor authentication reduces account security until it is re-enabled.
• Recommended only for administrative recovery or troubleshooting scenarios.

Archives imported Google Analytics data so it becomes available in Matomo reports.

./console googleanalyticsimporter:archive-imported-data

• Typically used after importing Google Analytics data into Matomo.
• Can generate significant database activity on large imports.
• Suitable for automation and scheduled processing workflows.

Imports Google Analytics 4 reports into Matomo sites.

./console googleanalyticsimporter:import-ga4-reports

• Used for migrations from Google Analytics 4 to Matomo.
• Large imports may take a significant amount of time to complete.
• Recommended to monitor database and API usage during imports.

Migrates token authentication values from Matomo 3 to the Matomo 4 authentication system.

./console core:matomo4-migrate-token-auths

• Typically run once during migration from Matomo 3 to Matomo 4.
• Useful when token authentication migration did not complete automatically.
• Recommended to back up the database before running migration commands.

Migrates annotations into the dedicated annotations database table introduced in Matomo 5.5.

./console core:matomo550-migrate-annotations

• Typically run once after upgrading to Matomo 5.5.
• Required before legacy annotation data can be removed safely.
• Recommended to complete during maintenance windows on large environments.

Removes legacy annotation data after annotations have been migrated successfully.

./console core:matomo550-purge-legacy-annotations

• Run only after confirming annotation migration completed successfully.
• Permanently removes legacy annotation storage data.
• Recommended to back up the database before execution.

Migrates legacy user-scoped settings into the plugin settings system introduced in Matomo 5.9.

./console core:matomo590-migrate-user-scoped-settings

• Typically run once after upgrading to Matomo 5.9.
• Useful when user-scoped settings migration did not complete automatically.
• Recommended to back up the database before running migration commands.

Activates one or more Matomo plugins.

./console plugin:activate RollUpReporting LogViewer ActivityLog AbTesting

Multiple plugins can be activated in a single command, making bulk changes fast and scriptable.
This approach is commonly used in automated upgrade and deployment workflows.

• Commonly used for deployment automation and scripted upgrades.
• Plugin activation may trigger cache rebuilding or database updates.
• Recommended to verify plugin compatibility before activation.

Deactivates one or more Matomo plugins.

./console plugin:deactivate RollUpReporting LogViewer ActivityLog AbTesting

• Used for troubleshooting, maintenance, and bulk plugin management.
• Deactivating plugins may disable related reports or features immediately.
• Recommended during maintenance windows for production environments.

Installs or updates a Matomo plugin.

./console plugin:install-or-update ExamplePlugin

• Used in scripted deployments and plugin upgrade workflows.
• Plugin updates may include database migrations or compatibility changes.
• Recommended to back up files and databases before major plugin updates.

Displays all installed Matomo plugins and shows which plugins are currently active.

./console plugin:list

This command helps verify which plugins are installed, activated, or available on the server.
Many Matomo features such as Funnels, Heatmaps, and Custom Dimensions are delivered through plugins.

• Helps with diagnostics, upgrade planning, and plugin troubleshooting.
• Identify outdated, unused, or incompatible plugins.
• Inactive plugins still exist on the server and should be reviewed regularly.

Uninstalls a Matomo plugin.

./console plugin:uninstall ExamplePlugin

• May permanently remove plugin-specific data or configuration.
• Recommended to deactivate plugins before uninstalling them.
• Useful for housekeeping and removing unused functionality.

Sets the Matomo Marketplace license key used for premium features.

./console marketplace:set-license-key your-license-key

• Used for automated deployments and Marketplace plugin updates.
• Required for downloading or updating commercial plugins.
• Recommended to store license keys securely.

Adds a new Custom Dimension to Matomo.

./console customdimensions:add-custom-dimension

• Used in deployment automation and analytics configuration workflows.
• Adding dimensions may affect report structure and archive generation.
• Recommended to plan dimensions carefully before deployment.

Displays information about installed Custom Dimensions.

./console customdimensions:info

• Helps to validate analytics configuration and troubleshooting dimension setups.
• Safe for unattended execution.
• Does not modify analytics data.

Removes an existing Custom Dimension.

./console customdimensions:remove-custom-dimension

• May affect existing reports and historical analytics data.
• Recommended to review reporting dependencies before removal.
• Useful during analytics cleanup or configuration restructuring.

Archives Custom Reports for specified sites and date ranges.

./console customreports:archive

• Used when rebuilding or pre-processing Custom Reports.
• Can increase database and CPU load on large environments.
• Suitable for recurring archive automation workflows.

Removes stored heatmap screenshots from the Heatmap & Session Recording plugin. You can also use the command to retake the screenshot of an already finished heatmap. Matomo temporarily restarts the heatmap and collects up to 50 new samples to generate a replacement screenshot automatically.

./console heatmapsessionrecording:remove-heatmap-screenshot --idsite={idsite} --idheatmap={idHeatmap}

• Requires both the Matomo site ID (idsite) and the heatmap ID (idHeatmap).
• Useful for storage cleanup, housekeeping, or regenerating outdated screenshots.
• Removing screenshots may temporarily affect heatmap visualisations until a new screenshot is generated.
• Recommended to verify screenshots are no longer required before deletion.

Manually import Bing keyword data for the specified Matomo site.

./console searchengines:import-bing --idsite={idSite}

• Requires a valid site ID using the --idsite option.
• Intended for enriching organic search reporting data.
• Suitable for scheduled import workflows.
• Import duration depends on available keyword data.

Manually import Google keyword data for the specified Matomo site.

./console searchengines:import-google --idsite={idSite}

• Requires a valid site ID using the --idsite option.
• Intended for enriching organic search reporting data.
• Safe for unattended execution and scheduled imports.
• Import behaviour depends on external search engine data availability.

Manually import Yandex keyword data for the specified Matomo site.

./console searchengines:import-yandex --idsite={idSite}

• Requires a valid site ID using the --idsite option.
• Intended for enriching organic search reporting data.
• Safe for recurring scheduled imports.
• Import duration depends on available keyword datasets.

Re-generates all released Tag Manager container files.

./console tagmanager:regenerate-released-containers

• Used after deployment, migration, or configuration changes.
• Ensures released Tag Manager containers are rebuilt correctly.
• Safe to run on production systems.

Re-attributes existing visits and conversions with geolocation data using the configured location provider.

./console usercountry:attribute

• Typically used after enabling or changing a geolocation provider.
• Can update historical raw visit and conversion data.
• May take time on large datasets, so run during low traffic periods.

Converts FIPS region codes saved by the legacy GeoIP provider to ISO region codes.

./console usercountry:convert-region-codes

• Used after migrating from legacy GeoIP region data.
• Can update stored location data.
• Recommended to back up the database before running data conversion commands.

Enables Matomo development mode.

./console development:enable

• For plugin and platform development workflows.
• Development mode may reduce performance and expose additional debugging information.
• Not recommended for production environments.

Parses and executes a query through the Matomo CLI multi-request system.

./console climulti:request

• Intended for internal or advanced administrative usage.
• Typically used by automation workflows or system integrations.
• Recommended only for experienced administrators or developers.

Updates the JavaScript tracker with plugin tracker additions and modifications.

./console custom-piwik-js:update

• Commonly used after installing, updating, or removing plugins that modify tracking behaviour.
• Recommended after plugin deployment workflows.
• Safe for unattended execution.