CLI task and schedules

CLI: Task and Schedule Management Commands

The task:*, backup:schedule:*, and scanner:schedule:* namespaces give you direct control over Panopticon's background task engine — the scheduler that drives all automatic monitoring, updates, and notifications. Understanding these commands is essential for troubleshooting stalled tasks, scripting batch operations, and managing per-site backup and scanner schedules programmatically.

task namespace

task:run

The core command that the CRON job executes. It picks the next due task off the queue, runs it, and exits — or, with --loop, stays alive and keeps processing tasks as they become due.

# Run one task cycle and exit (basic CRON usage)
php cli/panopticon.php task:run

# Stay alive and keep processing — recommended for CRON jobs
php cli/panopticon.php task:run --loop

The --loop option is strongly recommended in your CRON entry. Without it, a new PHP process must start every minute and will only run one task batch per invocation. With --loop, the process stays alive and processes tasks continuously, greatly reducing the latency between a task becoming due and it actually running.

CRON entry: * * * * * /path/to/php /path/to/panopticon/cli/panopticon.php task:run --loop

The --dummy option exists only for compatibility with CRON systems that pass an argument automatically; its value is always ignored.

---

task:list

Lists all scheduled tasks with their IDs, types, and status. This is your starting point when you need a task's numeric ID for task:enable, task:disable, or task:delete.

# List all tasks
php cli/panopticon.php task:list

# Filter by type keyword
php cli/panopticon.php task:list --search joomla

# Machine-readable output for scripting
php cli/panopticon.php task:list --format json

# Count how many tasks are registered
php cli/panopticon.php task:list --format count

---

task:enable / task:disable

Enables or disables a specific scheduled task by its numeric ID. A disabled task is skipped during each task:run pass — it stays in the queue but will not execute until re-enabled.

php cli/panopticon.php task:enable 12
php cli/panopticon.php task:disable 12

Use task:disable to prevent a task from running temporarily — for example, while you are performing maintenance that would interfere with it — without deleting the task entirely.

---

task:delete

Permanently removes a scheduled task by its numeric ID. System tasks that Panopticon manages automatically will be recreated on the next pass; site-specific tasks (backup schedules, scanner schedules) are gone permanently.

php cli/panopticon.php task:delete 12

---

task:pause / task:unpause

Pauses or resumes all background task processing globally. While paused, task:run will not execute any tasks — the CRON job continues running but nothing actually happens until you unpause.

# Pause all task processing
php cli/panopticon.php task:pause

# Resume task processing
php cli/panopticon.php task:unpause

This is the recommended way to take Panopticon's background engine offline during a maintenance window, a database migration, or an upgrade. Always unpause when you are done — leaving tasks paused indefinitely means no updates, no monitoring, and no notifications.

The selfupdate:run command uses task:pause internally during the update process.

---

task:sendmail

Processes the outgoing email queue immediately. Panopticon queues emails internally rather than sending them synchronously; this command flushes the queue. Normally the queue is processed automatically during task:run passes.

php cli/panopticon.php task:sendmail

Use this when you want to verify that email delivery is working, or to force-send queued emails after fixing a mail configuration problem.

---

task:joomlaupdate:director

Scans all Joomla! sites and enqueues automatic core update tasks for sites that are due for an update, based on their configured update schedule. This is the "director" step — it decides which sites need updating and adds the actual update tasks to the queue; task:run then executes those tasks.

# Process all Joomla! sites
php cli/panopticon.php task:joomlaupdate:director

# Process specific sites only
php cli/panopticon.php task:joomlaupdate:director --id 3 --id 7

# Force processing even if sites were recently checked
php cli/panopticon.php task:joomlaupdate:director --force

# Force-enqueue sites for updates even if they don't seem to need it
php cli/panopticon.php task:joomlaupdate:director --force --force_queue

# Control how many sites are evaluated per batch
php cli/panopticon.php task:joomlaupdate:director --batchSize 25

You would not normally call this manually — task:run handles it on schedule. Use it when you need to force an immediate update cycle outside the normal schedule, or when debugging why a site is not being queued for updates.

---

task:extensionupdates:director

The equivalent of task:joomlaupdate:director for Joomla! extension updates. Scans sites and enqueues extension update tasks for sites that have pending extension updates and are configured to install them automatically.

php cli/panopticon.php task:extensionupdates:director
php cli/panopticon.php task:extensionupdates:director --id 3
php cli/panopticon.php task:extensionupdates:director --force

---

task:wordpressupdate:director

Scans all WordPress sites and enqueues automatic core update tasks for sites that are due for a WordPress core update.

php cli/panopticon.php task:wordpressupdate:director
php cli/panopticon.php task:wordpressupdate:director --id 5
php cli/panopticon.php task:wordpressupdate:director --force --force_queue

---

task:pluginupdates:director

The equivalent of task:extensionupdates:director for WordPress plugin and theme updates.

php cli/panopticon.php task:pluginupdates:director
php cli/panopticon.php task:pluginupdates:director --id 5
php cli/panopticon.php task:pluginupdates:director --force

---

backup:schedule namespace

These commands manage per-site backup schedules — the recurring Akeeba Backup jobs Panopticon runs on your managed sites. Each schedule links a site, a CRON expression, and an Akeeba Backup profile. These are distinct from Panopticon's own database backups (see Database Backups).

---

backup:schedule:list

Lists all backup schedules. Without filtering, shows schedules for all sites.

# List all backup schedules
php cli/panopticon.php backup:schedule:list

# Filter to schedules for a specific site
php cli/panopticon.php backup:schedule:list --site-id 3

# JSON output for scripting
php cli/panopticon.php backup:schedule:list --format json

---

backup:schedule:get

Shows the full details of a specific backup schedule, including the CRON expression and all configuration options.

php cli/panopticon.php backup:schedule:get 7
php cli/panopticon.php backup:schedule:get 7 --format json

---

backup:schedule:add

Creates a new backup schedule for a site.

# Nightly backup at 01:00 UTC using profile 1
php cli/panopticon.php backup:schedule:add \
    --site-id 3 \
    --cron "0 1 * * *" \
    --profile-id 1 \
    --description "Nightly full backup" \
    --email-fail 1

# Weekly backup on Sunday at 03:00 UTC, email on both success and failure
php cli/panopticon.php backup:schedule:add \
    --site-id 3 \
    --cron "0 3 * * 0" \
    --profile-id 2 \
    --description "Weekly archive" \
    --email-success 1 \
    --email-fail 1

Option	Description
-s, --site-id	Numeric ID of the site (required)
--cron	CRON expression for the schedule (required)
--profile-id	Akeeba Backup profile ID to use (default: 1)
--description	Description stored in the backup record
--email-success	Send email on success: 1 (yes) or 0 (no, default)
--email-fail	Send email on failure: 1 (yes, default) or 0 (no)

---

backup:schedule:set

Updates an existing backup schedule. Only the options you specify are changed; omitted options keep their current values.

# Change the schedule time
php cli/panopticon.php backup:schedule:set 7 --cron "0 2 * * *"

# Switch to a different backup profile
php cli/panopticon.php backup:schedule:set 7 --profile-id 3

# Enable success emails
php cli/panopticon.php backup:schedule:set 7 --email-success 1

# Update description
php cli/panopticon.php backup:schedule:set 7 --description "Updated nightly backup"

---

backup:schedule:enable / backup:schedule:disable / backup:schedule:delete

Enable, disable, or permanently delete a backup schedule by its numeric ID.

php cli/panopticon.php backup:schedule:enable 7
php cli/panopticon.php backup:schedule:disable 7
php cli/panopticon.php backup:schedule:delete 7

---

scanner:schedule namespace

These commands manage per-site PHP File Change Scanner schedules — recurring Admin Tools scans that detect unexpected file modifications on your managed Joomla! sites. Admin Tools Professional must be installed on the site for these to work.

---

scanner:schedule:list

Lists all scanner schedules, with optional filtering by site.

php cli/panopticon.php scanner:schedule:list
php cli/panopticon.php scanner:schedule:list --site-id 3
php cli/panopticon.php scanner:schedule:list --format json

---

scanner:schedule:get

Shows the full details of a specific scanner schedule.

php cli/panopticon.php scanner:schedule:get 5
php cli/panopticon.php scanner:schedule:get 5 --format json

---

scanner:schedule:add

Creates a new scanner schedule for a site.

# Scan daily at 04:00 UTC
php cli/panopticon.php scanner:schedule:add \
    --site-id 3 \
    --cron "0 4 * * *"

# Scan twice a week (Monday and Thursday at midnight)
php cli/panopticon.php scanner:schedule:add \
    --site-id 3 \
    --cron "0 0 * * 1,4"

Option	Description
-s, --site-id	Numeric ID of the site (required)
--cron	CRON expression for the schedule (required)

---

scanner:schedule:set

Updates the CRON expression of an existing scanner schedule.

php cli/panopticon.php scanner:schedule:set 5 --cron "0 5 * * *"

---

scanner:schedule:enable / scanner:schedule:disable / scanner:schedule:delete

Enable, disable, or permanently delete a scanner schedule by its numeric ID.

php cli/panopticon.php scanner:schedule:enable 5
php cli/panopticon.php scanner:schedule:disable 5
php cli/panopticon.php scanner:schedule:delete 5

---

Common workflows

Setting up backup and scanner schedules for a new site

SITE_ID=42

# Daily backup at 01:30 UTC
php cli/panopticon.php backup:schedule:add \
    --site-id $SITE_ID \
    --cron "30 1 * * *" \
    --description "Nightly backup" \
    --email-fail 1

# Weekly full backup on Sunday at 02:00 UTC using profile 2
php cli/panopticon.php backup:schedule:add \
    --site-id $SITE_ID \
    --cron "0 2 * * 0" \
    --profile-id 2 \
    --description "Weekly full backup" \
    --email-success 1 \
    --email-fail 1

# Daily scanner at 04:00 UTC
php cli/panopticon.php scanner:schedule:add \
    --site-id $SITE_ID \
    --cron "0 4 * * *"

Maintenance window — pause and resume all tasks

# Before maintenance
php cli/panopticon.php task:pause
echo "Tasks paused. Performing maintenance..."

# ... your maintenance steps ...

# After maintenance
php cli/panopticon.php task:unpause
echo "Tasks resumed."

Diagnosing a stuck task runner

If Panopticon's background tasks have stopped running, you can check the state with:

# Look for tasks in a running/locked state
php cli/panopticon.php task:list --format json | jq '.[] | select(.status == "running")'

# Check if tasks are paused globally
php cli/panopticon.php config:get finished_setup

If tasks appear permanently stuck, task:pause followed by task:unpause clears any global pause flag. Individual stuck tasks may need to be deleted and recreated.

Exporting all backup schedules for documentation or migration

php cli/panopticon.php backup:schedule:list --format json > backup-schedules.json
php cli/panopticon.php scanner:schedule:list --format json > scanner-schedules.json