# Nextcloud occ — Maintenance and Administration via CLI

> Practical guide to Nextcloud occ — manage maintenance, users, apps, database and upgrades from the command line as the web server user.

Source: https://www.jpkc.com/db/en/cheatsheets/build-languages/nextcloud-occ/

<!-- PROSE:intro -->
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.
<!-- PROSE:intro:end -->

## Basic Usage

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

```bash
sudo -u www-data php occ list
```

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

```bash
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.

```bash
sudo -u www-data php occ status
```

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

```bash
sudo -u www-data php occ -V
```

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

```bash
sudo -u www-data php occ check
```

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

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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).

```bash
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.

```bash
sudo -u www-data php occ upgrade
```

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

```bash
sudo -u www-data php occ update:check
```

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

```bash
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.

```bash
sudo -u www-data php occ app:list
```

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

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

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

```bash
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.

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

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

```bash
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.

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

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

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
sudo -u www-data php occ user:report
```

## Group Management

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

```bash
sudo -u www-data php occ group:list
```

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

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

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

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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).

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
# 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.

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
sudo -u www-data php occ encryption:disable
```

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

```bash
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).

```bash
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.

```bash
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).

```bash
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.

```bash
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').

```bash
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.

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

## Sharing & Federation

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

```bash
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).

```bash
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.

```bash
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).

```bash
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).

```bash
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).

```bash
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.

```bash
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.

```bash
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.

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

<!-- PROSE:outro -->
## 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.

## Further Reading

- [Nextcloud occ command – Admin Manual](https://docs.nextcloud.com/server/latest/admin_manual/occ_command.html) – the official reference for all occ commands
- [Nextcloud Admin Manual](https://docs.nextcloud.com/server/latest/admin_manual/) – complete server administration documentation
<!-- PROSE:outro:end -->

## Related Commands

- [artisan](https://www.jpkc.com/db/en/cheatsheets/build-languages/artisan/) – command-line tool for the Laravel PHP framework
- [cargo](https://www.jpkc.com/db/en/cheatsheets/build-languages/cargo/) – package manager and build tool for Rust
- [composer](https://www.jpkc.com/db/en/cheatsheets/build-languages/composer/) – dependency manager for PHP