Nextcloud occ — Maintenance and Administration via CLI

occ is Nextcloud's administration and maintenance tool – a command-line interface that lets you control your instance without going through the web UI. Because occ has to run as the web server user, you typically invoke it with sudo -u www-data php occ <command> from the Nextcloud root directory – otherwise it writes files with the wrong ownership and leaves your installation in a mess. From maintenance mode and upgrades to user, group, and app management all the way to database repairs and LDAP, occ covers virtually every admin task. This guide walks you through the commands you reach for daily.

Basic Usage

sudo -u www-data php occ list — List all available occ commands. Run from the Nextcloud root directory.

sudo -u www-data php occ list

sudo -u www-data php occ help <command> — Show help and all options for a specific command.

sudo -u www-data php occ help files:scan

sudo -u www-data php occ status — Show the Nextcloud status: version, installed state, and maintenance mode.

sudo -u www-data php occ status

sudo -u www-data php occ -V — Show the Nextcloud and occ version.

sudo -u www-data php occ -V

sudo -u www-data php occ check — Run a basic system check (PHP version, database, loaded modules).

sudo -u www-data php occ check

Run occ inside a Docker container or DDEV environment as the web server user.

# Docker / container:
docker exec -u www-data nextcloud php occ <command>
# DDEV:
ddev exec -u www-data php occ <command>

Maintenance Mode

sudo -u www-data php occ maintenance:mode --on — Enable maintenance mode. All users are logged out and the site shows a maintenance message.

sudo -u www-data php occ maintenance:mode --on

sudo -u www-data php occ maintenance:mode --off — Disable maintenance mode and make Nextcloud accessible again.

sudo -u www-data php occ maintenance:mode --off

sudo -u www-data php occ maintenance:repair — Run the repair routine: fixes database inconsistencies, missing indices, and other common issues.

sudo -u www-data php occ maintenance:repair

sudo -u www-data php occ maintenance:repair --include-expensive — Run repair including expensive operations (e.g. filecache cleanup). Takes longer but more thorough.

sudo -u www-data php occ maintenance:repair --include-expensive

sudo -u www-data php occ maintenance:update:htaccess — Update the .htaccess file (run after changing the data directory or moving the installation).

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

sudo -u www-data php occ maintenance:data-fingerprint — Update the data fingerprint after restoring from backup. Prevents sync errors on clients.

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

Rebuild the MIME type database and update the JavaScript MIME type list (run after adding custom MIME types).

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

Upgrade & Updates

sudo -u www-data php occ upgrade — Run the Nextcloud upgrade after replacing the code with a newer version. Runs DB migrations and repairs.

sudo -u www-data php occ upgrade

sudo -u www-data php occ update:check — Check if a new Nextcloud version is available.

sudo -u www-data php occ update:check

Recommended upgrade sequence: enable maintenance mode, replace files, run upgrade, disable maintenance mode.

sudo -u www-data php occ maintenance:mode --on
# Replace Nextcloud files here
sudo -u www-data php occ upgrade
sudo -u www-data php occ maintenance:mode --off

App Management

sudo -u www-data php occ app:list — List all installed apps with their enabled/disabled status and version.

sudo -u www-data php occ app:list

sudo -u www-data php occ app:enable <appid> — Enable an installed app.

sudo -u www-data php occ app:enable calendar

sudo -u www-data php occ app:disable <appid> — Disable an app without removing it.

sudo -u www-data php occ app:disable activity

sudo -u www-data php occ app:install <appid> — Download and install an app from the Nextcloud App Store.

sudo -u www-data php occ app:install notes

sudo -u www-data php occ app:remove <appid> — Remove (uninstall) an app completely.

sudo -u www-data php occ app:remove notes

sudo -u www-data php occ app:update <appid> — Update a specific app to the latest version.

sudo -u www-data php occ app:update calendar

sudo -u www-data php occ app:update --all — Update all installed apps at once.

sudo -u www-data php occ app:update --all

sudo -u www-data php occ app:getpath <appid> — Show the filesystem path of an installed app.

sudo -u www-data php occ app:getpath files_sharing

User Management

sudo -u www-data php occ user:list — List all users. Use --output=json for machine-readable output.

sudo -u www-data php occ user:list

sudo -u www-data php occ user:info <uid> — Show detailed information about a specific user (display name, email, groups, quota, storage).

sudo -u www-data php occ user:info alice

sudo -u www-data php occ user:add <uid> --display-name=<name> --group=<group> — Create a new user. You will be prompted for a password unless --password-from-env is used.

sudo -u www-data php occ user:add alice --display-name='Alice Liddell' --group=users

sudo -u www-data php occ user:delete <uid> — Delete a user and their data from Nextcloud.

sudo -u www-data php occ user:delete alice

sudo -u www-data php occ user:resetpassword <uid> — Reset the password for a user. You will be prompted to enter the new password.

sudo -u www-data php occ user:resetpassword alice

sudo -u www-data php occ user:disable <uid> — Disable a user account (prevents login but keeps data).

sudo -u www-data php occ user:disable alice

sudo -u www-data php occ user:enable <uid> — Re-enable a previously disabled user account.

sudo -u www-data php occ user:enable alice

sudo -u www-data php occ user:setting <uid> <app> <key> <value> — Set a user-specific setting (e.g. language, quota). Omit value to read the current setting.

sudo -u www-data php occ user:setting alice core lang de

sudo -u www-data php occ user:report — Show total user count including LDAP and SSO users.

sudo -u www-data php occ user:report

Group Management

sudo -u www-data php occ group:list — List all groups.

sudo -u www-data php occ group:list

sudo -u www-data php occ group:info <group> — Show all members of a group.

sudo -u www-data php occ group:info admin

sudo -u www-data php occ group:add <group> — Create a new group.

sudo -u www-data php occ group:add developers

sudo -u www-data php occ group:delete <group> — Delete a group (does not delete the users in it).

sudo -u www-data php occ group:delete developers

sudo -u www-data php occ group:adduser <group> <uid> — Add a user to a group.

sudo -u www-data php occ group:adduser developers alice

sudo -u www-data php occ group:removeuser <group> <uid> — Remove a user from a group.

sudo -u www-data php occ group:removeuser developers alice

File Scanning & Cleanup

sudo -u www-data php occ files:scan --all — Scan all users' files and update the filecache. Run after adding files directly to the data directory.

sudo -u www-data php occ files:scan --all

sudo -u www-data php occ files:scan <uid> — Scan files for a specific user only.

sudo -u www-data php occ files:scan alice

sudo -u www-data php occ files:scan --path=<uid>/files/<subdir> — Scan a specific subdirectory for a user.

sudo -u www-data php occ files:scan --path=alice/files/Photos

sudo -u www-data php occ files:cleanup — Clean up orphaned filecache entries for storage that no longer exists.

sudo -u www-data php occ files:cleanup

sudo -u www-data php occ files:repair-tree — Repair the filecache tree structure (fixes parent-child relationships).

sudo -u www-data php occ files:repair-tree

sudo -u www-data php occ files:troubleshoot-transfer-ownership — Find and fix issues with file ownership transfers.

sudo -u www-data php occ files:troubleshoot-transfer-ownership

sudo -u www-data php occ files:transfer-ownership <source-uid> <dest-uid> — Transfer all files and shares from one user to another (e.g. when offboarding).

sudo -u www-data php occ files:transfer-ownership alice bob

sudo -u www-data php occ trashbin:cleanup --all-users — Empty the trash bin for all users.

sudo -u www-data php occ trashbin:cleanup --all-users

sudo -u www-data php occ trashbin:cleanup <uid> — Empty the trash bin for a specific user.

sudo -u www-data php occ trashbin:cleanup alice

sudo -u www-data php occ versions:cleanup <uid> — Delete all stored file versions for a specific user to free up disk space.

sudo -u www-data php occ versions:cleanup alice

Database

sudo -u www-data php occ db:add-missing-indices — Add missing database indices. Greatly improves performance. Safe to run on a live instance.

sudo -u www-data php occ db:add-missing-indices

sudo -u www-data php occ db:add-missing-primary-keys — Add missing primary keys to database tables. Required for some upgrades.

sudo -u www-data php occ db:add-missing-primary-keys

sudo -u www-data php occ db:add-missing-columns — Add missing columns that were introduced in newer Nextcloud versions.

sudo -u www-data php occ db:add-missing-columns

sudo -u www-data php occ db:convert-filecache-bigint — Convert filecache IDs to bigint. Required for large instances (>4 billion files). Takes a while.

sudo -u www-data php occ db:convert-filecache-bigint

sudo -u www-data php occ db:convert-type --all-apps <type> <user> <host> <db> — Migrate the Nextcloud database to a different database type (e.g. SQLite to MySQL/PostgreSQL).

sudo -u www-data php occ db:convert-type mysql ncuser localhost nextcloud

Background Jobs

sudo -u www-data php occ background:cron — Set the background job execution mode to system cron (recommended).

sudo -u www-data php occ background:cron

sudo -u www-data php occ background:webcron — Set background jobs to run via webcron (an external service calls /cron.php).

sudo -u www-data php occ background:webcron

sudo -u www-data php occ background:ajax — Set background jobs to run via AJAX (triggered by page loads). Not suitable for production.

sudo -u www-data php occ background:ajax

sudo -u www-data php occ background:job:execute <job-id> — Manually execute a specific background job by its ID.

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

sudo -u www-data php occ background:job:list — List all registered background jobs with their last run time and status.

sudo -u www-data php occ background:job:list

Cron entry to run Nextcloud background jobs every 5 minutes. Add to /etc/crontab or crontab -u www-data.

# Recommended crontab entry (run as root or www-data):
*/5 * * * * www-data php /var/www/html/nextcloud/cron.php

Configuration

sudo -u www-data php occ config:list — List all system and app configuration values. Passwords are masked.

sudo -u www-data php occ config:list

sudo -u www-data php occ config:list system — List only system configuration (equivalent to config.php contents).

sudo -u www-data php occ config:list system

sudo -u www-data php occ config:system:get <key> — Get the value of a system configuration key.

sudo -u www-data php occ config:system:get version

sudo -u www-data php occ config:system:set <key> --value=<value> — Set a system configuration value. Writes directly to config/config.php.

sudo -u www-data php occ config:system:set default_language --value=de

sudo -u www-data php occ config:system:set <key> --type=boolean --value=true — Set a boolean system config value. Types: string (default), boolean, integer, double.

sudo -u www-data php occ config:system:set maintenance --type=boolean --value=true

sudo -u www-data php occ config:system:delete <key> — Delete a system configuration key from config.php.

sudo -u www-data php occ config:system:delete trusted_domains 1

Set trusted domains (allowed hostnames). Use array index 0, 1, 2... for multiple domains.

sudo -u www-data php occ config:system:set trusted_domains 0 --value=localhost
sudo -u www-data php occ config:system:set trusted_domains 1 --value=nextcloud.example.com

sudo -u www-data php occ config:app:get <appid> <key> — Get an app-specific configuration value.

sudo -u www-data php occ config:app:get mail smtp_host

sudo -u www-data php occ config:app:set <appid> <key> --value=<value> — Set an app-specific configuration value.

sudo -u www-data php occ config:app:set mail smtp_host --value=smtp.example.com

Security & Encryption

sudo -u www-data php occ security:certificates — List all imported trusted SSL root certificates.

sudo -u www-data php occ security:certificates

sudo -u www-data php occ security:certificates:import <path> — Import a custom CA certificate to trust it for outgoing connections (e.g. LDAP, SMTP).

sudo -u www-data php occ security:certificates:import /tmp/my-ca.crt

sudo -u www-data php occ security:certificates:remove <filename> — Remove a previously imported CA certificate.

sudo -u www-data php occ security:certificates:remove my-ca.crt

sudo -u www-data php occ encryption:status — Show whether server-side encryption is enabled and the active encryption module.

sudo -u www-data php occ encryption:status

sudo -u www-data php occ encryption:enable — Enable server-side encryption. Users must log in after enabling to encrypt their files.

sudo -u www-data php occ encryption:enable

sudo -u www-data php occ encryption:disable — Disable server-side encryption. All files must be decrypted first.

sudo -u www-data php occ encryption:disable

sudo -u www-data php occ twofactorauth:enforce --on — Enforce two-factor authentication for all users.

sudo -u www-data php occ twofactorauth:enforce --on

sudo -u www-data php occ twofactorauth:disable <uid> <provider> — Disable a specific 2FA provider for a user (e.g. to recover a locked-out account).

sudo -u www-data php occ twofactorauth:disable alice totp

Logging

sudo -u www-data php occ log:manage — Show the current log level and log backend configuration.

sudo -u www-data php occ log:manage

sudo -u www-data php occ log:manage --level=<level> — Set the log level. Levels: debug (0), info (1), warning (2), error (3), fatal (4).

sudo -u www-data php occ log:manage --level=warning

sudo -u www-data php occ log:manage --backend=file — Set the log backend. Options: file (default), syslog, errorlog, systemd.

sudo -u www-data php occ log:manage --backend=syslog

sudo -u www-data php occ log:tail — Tail the Nextcloud log file in real-time (requires log backend to be 'file').

sudo -u www-data php occ log:tail

sudo -u www-data php occ log:tail --lines=50 — Show the last 50 lines from the Nextcloud log.

sudo -u www-data php occ log:tail --lines=50

sudo -u www-data php occ sharing:cleanup-remote-storages — Clean up orphaned remote shares (federated sharing leftovers after user deletion).

sudo -u www-data php occ sharing:cleanup-remote-storages

sudo -u www-data php occ config:app:set core shareapi_enabled --value=yes — Enable the sharing API (allows users to share files).

sudo -u www-data php occ config:app:set core shareapi_enabled --value=yes

sudo -u www-data php occ config:app:set core shareapi_allow_links --value=no — Disable public link sharing for all users.

sudo -u www-data php occ config:app:set core shareapi_allow_links --value=no

LDAP / Active Directory

sudo -u www-data php occ ldap:show-config — Show the current LDAP configuration (connection, base DN, filters).

sudo -u www-data php occ ldap:show-config

sudo -u www-data php occ ldap:test-config <config-id> — Test the LDAP connection for a specific configuration prefix (e.g. s01).

sudo -u www-data php occ ldap:test-config s01

sudo -u www-data php occ ldap:search --group '' --limit=10 — Search for LDAP groups (empty string returns all, limited to 10).

sudo -u www-data php occ ldap:search --group '' --limit=10

sudo -u www-data php occ ldap:check-user <uid> — Check if an LDAP user still exists and is active in the directory.

sudo -u www-data php occ ldap:check-user alice

sudo -u www-data php occ ldap:reset-cache — Clear the LDAP cache to force fresh lookups on next access.

sudo -u www-data php occ ldap:reset-cache

sudo -u www-data php occ user:sync 'OCA\User_LDAP\User_Proxy' -m remove — Sync LDAP users: remove Nextcloud accounts for users no longer in LDAP. Options: -m remove, disable, or ask.

sudo -u www-data php occ user:sync 'OCA\User_LDAP\User_Proxy' -m disable

Conclusion

occ is the Swiss Army knife of Nextcloud administration – almost everything you can set in the web UI (and plenty that you can only do here) is fast and scriptable from the command line. Always run occ as the correct web server user (sudo -u www-data php occ …); accidentally running it as root sets file permissions wrong and can take the instance down. Enable maintenance mode (maintenance:mode --on) before upgrades and larger operations, and back up your database and config/config.php before db:*, maintenance:repair, or resetting passwords (user:resetpassword) – config:system:set writes straight to the configuration. Treat it with that care and occ stays a powerful but safe tool.