System & maintenance commands

admin-delegation:add

Delegate an admin settings class to a group:

sudo -E -u www-data php occ admin-delegation:add \
  'OCA\Settings\Settings\Admin\Sharing' milliways

The settingClass argument must be the fully qualified PHP class name of a settings class that implements IDelegatedSettings. Common examples:

• OCA\Settings\Settings\Admin\Sharing — sharing administration

• OCA\Settings\Settings\Admin\Users — user management

• OCA\Settings\Settings\Admin\Mail — email configuration

• OCA\Theming\Settings\Admin — theming settings

admin-delegation:remove

Remove a settings delegation from a group:

sudo -E -u www-data php occ admin-delegation:remove \
  'OCA\Settings\Settings\Admin\Sharing' milliways

admin-delegation:show

Show all currently configured settings delegations:

sudo -E -u www-data php occ admin-delegation:show

Use --output=json_pretty for machine-readable output.

background:cron

Set the background job execution mode to cron. Nextcloud recommends the system cron mode for production instances:

sudo -E -u www-data php occ background:cron
  Set mode for background jobs to 'cron'

Use background:ajax to switch to the in-browser AJAX scheduler or background:webcron for an external webcron service instead.

See :doc:`../configuration_server/background_jobs_configuration` for a full guide to configuring the background job scheduler.

background-job:delete

Remove a background job from the database. The command shows the job details and asks for confirmation:

sudo -E -u www-data php occ background-job:delete 42
  Job class: OCA\Files\BackgroundJob\ScanFiles
  Arguments: []

  Do you really want to delete this background job? It could create some misbehaviours in Nextcloud. (y/N)

background-job:execute

Execute a single background job by its database ID:

sudo -E -u www-data php occ background-job:execute 42

The command shows the job's class, type, last run time, and next scheduled execution before running it. If the job was recently run and is not yet due, it may be skipped; use --force-execute to run it regardless:

sudo -E -u www-data php occ background-job:execute --force-execute 42

background-job:history

Show job history with their duration and peak memory usage:

sudo -E -u www-data php occ background-job:history -l 5
+-------------------+-----------+-------------------------------------------+---------------------+-----------+---------+-----------+--------------+
| Run ID            | Status    | Class                                     | Started at          | Server ID | PID     | Duration  | Memory usage |
+-------------------+-----------+-------------------------------------------+---------------------+-----------+---------+-----------+--------------+
| 98109593040965632 | Succeeded | OC\Command\CommandJob                     | 2026-06-22 09:15:19 | 30        | 3847229 | 284 ms    | 251.6 MB     |
| 98109592927719424 | Succeeded | OC\FilesMetadata\Job\UpdateSingleMetadata | 2026-06-22 09:15:19 | 30        | 3847229 | 16 ms     | 222 MB       |
| 98109592852221952 | Succeeded | OC\FilesMetadata\Job\UpdateSingleMetadata | 2026-06-22 09:15:19 | 30        | 3847229 | 8 ms      | 221.4 MB     |
| 98109588267847680 | Succeeded | OC\Command\CommandJob                     | 2026-06-22 09:15:18 | 30        | 3847229 | 909 ms    | 293 MB       |
| 97985889682313216 | Crashed   | OCA\Text\Cron\Cleanup                     | 2026-06-22 01:15:17 | 30        | 3733554 | 594627 ms | 0 B          |
+-------------------+-----------+-------------------------------------------+---------------------+-----------+---------+-----------+--------------+

Use -l/--limit to control how many jobs are shown (default: 200), one or multiple -c/--class to filter by job class, and one or multiple -s/--status to filter by status (0: running, 1: succeeded, 2: failed, 3: crashed).

background-job:list

List all background jobs registered in the database:

sudo -E -u www-data php occ background-job:list
+----+------------------------------------------------------+---------------------------+------------+
| id | class                                                | last_run                  | argument   |
+----+------------------------------------------------------+---------------------------+------------+
| 1  | OCA\Files\BackgroundJob\ScanFiles                    | 2025-06-23T10:00:00+00:00 | []         |
| 2  | OCA\Activity\BackgroundJob\DigestMail                | 2025-06-23T08:00:00+00:00 | []         |
| 3  | OC\Share20\SharesReminderJob                         | 2025-06-23T07:00:00+00:00 | []         |
+----+------------------------------------------------------+---------------------------+------------+

Use -c / --class to filter by job class, -l / --limit to control how many jobs are shown (default: 500), and -o / --offset to page through results.

background-job:running

List all currently running jobs:

sudo -E -u www-data php occ background-job:running
+-------------------+-----------------------+---------------------+-----------+---------+---------------+
| Run ID            | Class                 | Started at          | Server ID | PID     | Running since |
+-------------------+-----------------------+---------------------+-----------+---------+---------------+
| 98108257692012544 | OC\Command\CommandJob | 2026-06-22 09:10:08 | 30        | 3845056 | 1 seconds     |
+-------------------+-----------------------+---------------------+-----------+---------+---------------+

Use -l / --limit to limit the number of job shown (default: 200).

background-job:worker

Run a continuous background job worker. This is an alternative to system cron for environments where you want to run background jobs from a persistent process rather than a periodic cron invocation:

sudo -E -u www-data php occ background-job:worker

By default the worker runs indefinitely, polling for new jobs every second.

Use --once to process at most one job then exit (equivalent to a single cron run):

sudo -E -u www-data php occ background-job:worker --once

Use --stop_after to set a maximum runtime before the worker exits cleanly (the currently running job is allowed to finish). Accepts seconds, or values like 30s, 10m, 2h:

sudo -E -u www-data php occ background-job:worker --stop_after 1h

Use --interval to set the poll interval in seconds (default: 1). Set to 0 to process jobs once and exit if none are found:

sudo -E -u www-data php occ background-job:worker --interval 5

Pass one or more job class names to process only jobs of those types:

sudo -E -u www-data php occ background-job:worker \
  'OCA\Files\BackgroundJob\ScanFiles'

info:file

Show detailed information for a file or folder identified by file ID or path:

sudo -E -u www-data php occ info:file /layla/files/Documents/report.pdf
  FileId: 12345
  MimeType: application/pdf
  Modified: 2025-06-01T14:30:00+00:00
  Encrypted: false
  Size: 204800
  ETag: abc123
  Permissions: 27
  Users with access: layla

Use -c / --children to list the immediate contents of a folder. Use --storage-tree to display the storage and cache wrapping tree.

info:file:space

Show how much space a folder uses, with a ranked breakdown of the largest items:

sudo -E -u www-data php occ info:file:space /layla/files/Videos
  Total: 14.7 GB
  +------------------+--------+
  | Path             | Size   |
  +------------------+--------+
  | lecture-2025.mp4 | 8.2 GB |
  | demo-video.mp4   | 4.1 GB |
  +------------------+--------+

Use -c / --count to change the number of items shown (default: 25), or -a / --all to show all items.

info:storage

Show information for a single storage by its numeric storage ID:

sudo -E -u www-data php occ info:storage 5

info:storages

List all storages ordered by the number of files they contain:

sudo -E -u www-data php occ info:storages

Use -c / --count to limit the number of storages shown (default: 25), or -a / --all to list all storages.

log:file

Show the current logging status:

sudo -E -u www-data php occ log:file
  Log backend Nextcloud: enabled
  Log file: /opt/nextcloud/data/nextcloud.log
  Rotate at: disabled

Use --enable to turn on the Nextcloud log backend, --file to set a different log file path, and --rotate-size to rotate the log at a given file size in bytes (0 disables rotation).

log:manage

Set the logging backend, log level, and timezone. The defaults are file, warning, and UTC:

sudo -E -u www-data php occ log:manage --backend file --level warning --timezone UTC
  Log backend: file
  Log level: Warning (2)
  Log timezone: UTC

Options:

• --backend — one of: file, syslog, errorlog, systemd

• --level — one of: debug, info, warning, error, fatal

• --timezone — a PHP timezone name; see https://www.php.net/manual/en/timezones.php

maintenance:data-fingerprint

After restoring a backup of your data directory or the database, run this command once. It updates the ETag for all files, allowing sync clients to detect that files were modified:

sudo -E -u www-data php occ maintenance:data-fingerprint

maintenance:mimetype:update-db and maintenance:mimetype:update-js

Update the Nextcloud database and file cache with changed mimetypes from config/mimetypemapping.json. Run after modifying that file. Pass --repair-filecache to apply the change to existing files:

sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache

maintenance:mimetype:update-js regenerates the client-side mimetype list:

sudo -E -u www-data php occ maintenance:mimetype:update-js

maintenance:mode

Lock the sessions of all logged-in users, including administrators, and display a status screen warning that the server is in maintenance mode. Users who are not already logged in cannot log in until maintenance mode is turned off. When the server comes out of maintenance mode, logged-in users must refresh their browser to continue working:

sudo -E -u www-data php occ maintenance:mode --on
  Maintenance mode enabled

sudo -E -u www-data php occ maintenance:mode --off
  Maintenance mode disabled

maintenance:repair

Runs automatically during upgrades to clean up the database. You can also run it manually if needed:

sudo -E -u www-data php occ maintenance:repair

maintenance:repair-share-owner

Fix share owner records that have fallen out of sync with the actual file ownership:

sudo -E -u www-data php occ maintenance:repair-share-owner

maintenance:theme:update

Run when icons in a custom theme are not updating correctly. This rebuilds the mimetype list and clears the image cache:

sudo -E -u www-data php occ maintenance:theme:update

maintenance:update:htaccess

Regenerate the .htaccess file from the current configuration. Run this after changing URL rewriting settings or after an upgrade if the file appears outdated:

sudo -E -u www-data php occ maintenance:update:htaccess

security:bruteforce:attempts

Show the current bruteforce throttle status for an IP address, including the number of recorded attempts and the current delay being applied. Optionally filter by action name:

sudo -E -u www-data php occ security:bruteforce:attempts 192.168.1.100
sudo -E -u www-data php occ security:bruteforce:attempts 192.168.1.100 login

Use --output=json_pretty for machine-readable output.

security:bruteforce:reset

Clear all recorded bruteforce attempts for an IP address, removing any login delay immediately:

sudo -E -u www-data php occ security:bruteforce:reset 192.168.1.100

security:certificates

List all trusted certificates installed on the server:

sudo -E -u www-data php occ security:certificates
+---------------------+-------------+-------------------+-------------+-----------+
| File Name           | Common Name | Organization      | Valid Until | Issued By |
+---------------------+-------------+-------------------+-------------+-----------+
| myserver.crt        | myserver    | My Org            | 2026-01-01  | My CA     |
+---------------------+-------------+-------------------+-------------+-----------+

Use --output=json_pretty for machine-readable output.

security:certificates:export

Export the full certificate bundle to stdout. Useful for backup or inspection:

sudo -E -u www-data php occ security:certificates:export

security:certificates:import

Install a trusted certificate from a file. The certificate name is derived from the filename:

sudo -E -u www-data php occ security:certificates:import /path/to/certificate.crt

security:certificates:remove

Remove a trusted certificate by its file name (as shown in security:certificates):

sudo -E -u www-data php occ security:certificates:remove my-certificate

share:list

List all shares on the system:

sudo -E -u www-data php occ share:list

Filter by owner, recipient, or the user who created the share:

sudo -E -u www-data php occ share:list --owner layla
sudo -E -u www-data php occ share:list --recipient fred
sudo -E -u www-data php occ share:list --by layla

Filter by a specific file path:

sudo -E -u www-data php occ share:list --file "/layla/files/Documents/report.pdf"

Filter by a folder; use --recursive to include shares nested anywhere inside it:

sudo -E -u www-data php occ share:list --parent "/layla/files/Projects" --recursive

Filter by share type (one of user, group, link, email, remote, room, deck) or by share status:

sudo -E -u www-data php occ share:list --type link
sudo -E -u www-data php occ share:list --status 0

Status return code

Use the -e flag to get a machine-readable exit code reflecting the installation state. There is no output by default, making it suitable for scripts, monitoring checks, and systemd units:

sudo -E -u www-data php occ status -e
echo $?
0
sudo -E -u www-data php occ maintenance:mode --on
Maintenance mode enabled
sudo -E -u www-data php occ status -e
echo $?
1
sudo -E -u www-data php occ maintenance:mode --off
Maintenance mode disabled
sudo -E -u www-data php occ status -e
echo $?
0

taskprocessing:task-type:set-enabled

Enable or disable a task type:

sudo -E -u www-data php occ taskprocessing:task-type:set-enabled core:text2text 1
sudo -E -u www-data php occ taskprocessing:task-type:set-enabled core:text2text 0

taskprocessing:task:cleanup

Delete old task records and their associated output files. By default, tasks older than four months are removed:

sudo -E -u www-data php occ taskprocessing:task:cleanup

Pass a maximum age in seconds to override the default:

sudo -E -u www-data php occ taskprocessing:task:cleanup 2592000

taskprocessing:task:get

Display all information for a specific task by its numeric ID:

sudo -E -u www-data php occ taskprocessing:task:get 42

taskprocessing:task:list

List task processing tasks:

sudo -E -u www-data php occ taskprocessing:task:list

Filter by user, type, app, or custom ID:

sudo -E -u www-data php occ taskprocessing:task:list --userIdFilter layla
sudo -E -u www-data php occ taskprocessing:task:list --type core:text2text

Filter by status (0=UNKNOWN, 1=SCHEDULED, 2=RUNNING, 3=SUCCESSFUL, 4=FAILED, 5=CANCELLED):

sudo -E -u www-data php occ taskprocessing:task:list --status 4

Other available filters: --appId, --customId, --scheduledAfter, --endedBefore.

taskprocessing:task:stats

Show statistics for tasks (max/average running time, queuing time, and input/output sizes). Accepts the same filter options as taskprocessing:task:list:

sudo -E -u www-data php occ taskprocessing:task:stats

taskprocessing:worker

Run a dedicated worker that processes tasks from synchronous TaskProcessing providers. Use this when you want to offload AI task execution to a separate process:

sudo -E -u www-data php occ taskprocessing:worker

Use --once to process at most one task then exit. Use --timeout to set a maximum runtime in seconds (default: 0 = run indefinitely). Use --taskTypes (repeatable) to restrict the worker to specific task type IDs:

sudo -E -u www-data php occ taskprocessing:worker \
  --taskTypes core:text2text --once

theming:config

With no arguments, show all current theming values:

sudo -E -u www-data php occ theming:config
  Current theming config:
  name: Nextcloud
  url: https://nextcloud.com
  slogan: a safe home for all your data
  ...

Show the current value of a single key:

sudo -E -u www-data php occ theming:config name

Set a value:

sudo -E -u www-data php occ theming:config name "Acme Cloud"
sudo -E -u www-data php occ theming:config url "https://acme.example.com"
sudo -E -u www-data php occ theming:config slogan "Secure file sync for Acme"
sudo -E -u www-data php occ theming:config primary_color "#0082c9"
sudo -E -u www-data php occ theming:config background_color "#00679e"
sudo -E -u www-data php occ theming:config disable-user-theming true

To set an image, pass the path to the image file as the value:

sudo -E -u www-data php occ theming:config logo /path/to/logo.png
sudo -E -u www-data php occ theming:config favicon /path/to/favicon.ico
sudo -E -u www-data php occ theming:config background /path/to/background.jpg

Reset a key to its default:

sudo -E -u www-data php occ theming:config --reset name

Supported text keys: name, url, imprintUrl, privacyUrl, slogan, primary_color, background_color, disable-user-theming.

Supported image keys: background, logo, logoheader, favicon.

workflows:list

List configured workflow rules. Use the optional scope argument to filter by scope; admin (default) or user:

sudo -E -u www-data php occ workflows:list
sudo -E -u www-data php occ workflows:list user
sudo -E -u www-data php occ workflows:list user layla

The output is a JSON representation of the configured workflow operations.

files_antivirus:background-scan

Trigger the background antivirus scan manually. By default all pending files are processed. Use --max to limit the number of files scanned in a single run:

sudo -E -u www-data php occ files_antivirus:background-scan
sudo -E -u www-data php occ files_antivirus:background-scan --max 500

files_antivirus:mark

Mark a file as scanned or unscanned. The file argument is the path to the file and mode is either scanned or unscanned:

sudo -E -u www-data php occ files_antivirus:mark /layla/files/report.pdf scanned
sudo -E -u www-data php occ files_antivirus:mark /layla/files/report.pdf unscanned

Use --forever (-f) when marking a file as scanned to permanently exclude it from future rescans:

sudo -E -u www-data php occ files_antivirus:mark --forever /layla/files/report.pdf scanned

files_antivirus:scan

Scan a single file immediately and report the result:

sudo -E -u www-data php occ files_antivirus:scan /layla/files/report.pdf

Use --debug to enable verbose backend output, useful when diagnosing scanner connectivity issues:

sudo -E -u www-data php occ files_antivirus:scan --debug /layla/files/report.pdf

files_antivirus:status

Show the current antivirus scanner status, including the configured backend and whether the scanner is reachable:

sudo -E -u www-data php occ files_antivirus:status

Use -v for additional backend detail.