CLI maintenance

CLI: Maintenance Commands

The mailtemplate:*, selfupdate:*, and log:* namespaces cover day-to-day maintenance of Panopticon itself: managing the email templates it sends, keeping the application up to date, and controlling log file growth.

mailtemplate namespace

Panopticon sends automated emails for events like available Joomla! updates, backup failures, and extension alerts. Every email type has a built-in default template; you can customise any of them through the web interface. The CLI commands let you export, import, and edit those customised templates without the UI — useful for keeping templates under version control, migrating them between instances, or deploying a standard set of branded templates across multiple Panopticon installations.

---

mailtemplate:list

Lists all stored mail templates. Templates only appear in this list if their content has been customised; types not listed here are using the built-in defaults.

# List all customised templates
php cli/panopticon.php mailtemplate:list

# Filter to templates matching a keyword
php cli/panopticon.php mailtemplate:list --search joomla

# JSON output for scripted inspection
php cli/panopticon.php mailtemplate:list --format json

---

mailtemplate:get

Retrieves the full content of a specific template, identified either by its numeric ID or by its type name (and optionally a language code). Use this to review the current content of a template before editing it.

The --only-html and --only-plaintext flags strip everything except the body, making it easy to pipe the output directly into an editor or file for modification.

# Get a template by its numeric ID
php cli/panopticon.php mailtemplate:get 7

# Get a template by type (uses the default/wildcard language)
php cli/panopticon.php mailtemplate:get joomlaupdate_found

# Get a language-specific variant
php cli/panopticon.php mailtemplate:get joomlaupdate_found --language el-GR

# Export just the HTML body for editing, then put it back
php cli/panopticon.php mailtemplate:get joomlaupdate_found --only-html > template.html
# ... edit template.html ...
php cli/panopticon.php mailtemplate:set:html joomlaupdate_found < template.html

---

mailtemplate:set

Creates or updates a mail template. You can supply the HTML body inline or pipe it from stdin. If you do not provide a plaintext body, one is automatically generated from the HTML.

# Create or update a template, supplying HTML inline
php cli/panopticon.php mailtemplate:set \
    --type joomlaupdate_found \
    --subject "Joomla! update available for {{SITE_NAME}}" \
    --html "$(cat my-template.html)"

# Pipe the HTML body from a file
php cli/panopticon.php mailtemplate:set \
    --type joomlaupdate_found \
    --subject "Joomla! update available for {{SITE_NAME}}" \
    < my-template.html

# Create a language-specific variant
php cli/panopticon.php mailtemplate:set \
    --type joomlaupdate_found \
    --language de-DE \
    --subject "Joomla!-Update für {{SITE_NAME}} verfügbar" \
    < german-template.html

Option	Description
-t, --type	Template type identifier (required)
-l, --language	Language code, default * (wildcard / all languages)
-s, --subject	Email subject line
--html	HTML body (reads from stdin if omitted)
-p, --plaintext	Plaintext body (auto-generated from HTML if omitted)

---

mailtemplate:set:html

Updates only the HTML body of an existing template, leaving the subject and all other fields unchanged. Use this when you want to refresh a template's visual design without touching its subject line or language settings.

# Update by template type
php cli/panopticon.php mailtemplate:set:html joomlaupdate_found < updated-template.html

# Update by numeric ID
php cli/panopticon.php mailtemplate:set:html 7 < updated-template.html

---

mailtemplate:set:plaintext

Updates only the plaintext body of an existing template. Useful if you want to maintain a hand-crafted plaintext version rather than relying on the auto-generated one.

php cli/panopticon.php mailtemplate:set:plaintext joomlaupdate_found < template.txt

---

mailtemplate:export

Exports all customised mail templates as SQL INSERT statements. Primary use cases:

• Backups before a Panopticon upgrade, in case the update process affects templates
• Migration of a customised template set from one Panopticon instance to another
• Version control — commit the exported SQL alongside your other configuration

# Export with the actual database table prefix
php cli/panopticon.php mailtemplate:export > mail-templates-backup.sql

# Export with a generic #__ prefix — importable into any Panopticon installation
php cli/panopticon.php mailtemplate:export --generic > mail-templates-portable.sql

# Migrate templates directly into another database
php cli/panopticon.php mailtemplate:export --generic | \
    mysql -u panopticon -p panopticon_other_db

Use --generic whenever you are exporting for migration or version control. The #__ placeholder is replaced with the correct table prefix at import time, making the file portable across installations with different database prefixes.

---

mailtemplate:delete

Deletes a customised template by its numeric ID. After deletion, Panopticon falls back to the built-in default for that template type. This is the correct way to "reset" a customised template back to its default — you do not need to recreate the default content manually.

php cli/panopticon.php mailtemplate:delete 7

---

selfupdate namespace

These commands manage Panopticon's own update process. The web interface has a built-in self-update feature, but the CLI equivalents are preferable when you are managing Panopticon through automation, running updates as part of a maintenance script, or operating in an environment where web-initiated updates are not reliable.

❗ Docker users: Do not use selfupdate:run inside a Docker container. The self-updater modifies the container's filesystem and the changes will not survive a container replacement. Update the container image instead.

---

selfupdate:notify

Checks whether a new version of Panopticon is available and, if one is found, sends notification emails to all Super Users. This is what the built-in selfupdatefinder system task does on its automatic schedule; this command lets you trigger the check on demand.

php cli/panopticon.php selfupdate:notify

Use this to check for updates outside the normal schedule, or when testing that notification emails are working correctly.

---

selfupdate:run

Downloads and installs the latest version of Panopticon over the current installation. Pauses background tasks during the process, downloads the release archive, and extracts it.

# Check for a new version and install it if available
php cli/panopticon.php selfupdate:run

# Force a re-check even if availability was checked very recently
php cli/panopticon.php selfupdate:run --force

After selfupdate:run finishes, run database:update and then selfupdate:cleanup to complete the process.

---

selfupdate:cleanup

Finalises the self-update process by running post-update routines: database schema migrations, cache clearing, and any other housekeeping the new version requires. Normally called automatically as part of selfupdate:run, but you can call it manually if the update was interrupted or if you are coordinating the steps yourself.

php cli/panopticon.php selfupdate:cleanup

Complete scripted update sequence

The recommended pattern for an unattended update:

php cli/panopticon.php selfupdate:run && \
php cli/panopticon.php database:update && \
php cli/panopticon.php selfupdate:cleanup

Using && ensures each step only runs if the previous one succeeded, preventing a partially-applied update from proceeding further.

---

log namespace

log:rotate

Rotates Panopticon's log files: the current log file is archived, a fresh log file is started, and archived logs beyond the configured retention count are deleted.

Normally log rotation runs automatically as a daily system task. Use the CLI command when you want to trigger it on demand — for example, after a heavy debugging session that produced a large verbose log you want to archive immediately, or as part of a maintenance script before taking a backup.

php cli/panopticon.php log:rotate

Example — nightly maintenance script:

#!/bin/bash
# Run from cron: 0 3 * * * /usr/bin/bash /opt/panopticon/nightly-maintenance.sh

cd /opt/panopticon

php cli/panopticon.php log:rotate
php cli/panopticon.php selfupdate:notify
php cli/panopticon.php database:backup