Command-line client

nextcloudcmd synchronizes a local directory with a Nextcloud server, then exits. It can perform follow-up syncs when needed, but it does not continuously monitor local files or poll for server changes like the desktop app. For options passed to the desktop app’s nextcloud command, see Command-line options.

Installation

Install a package that provides nextcloudcmd. Availability depends on your operating system and package:

Operating system	Package source
Alpine Linux	nextcloud-client
Debian	nextcloud-desktop-cmd
Fedora	nextcloud-client
Ubuntu	nextcloud-desktop-cmd
Ubuntu PPA	Nextcloud client PPA
Windows	Nextcloud downloads

Usage

Use an existing local directory and the base URL of the Nextcloud server:

nextcloudcmd [options] local_directory server_url

For example, synchronize the remote Music folder into an existing local folder:

nextcloudcmd --user carla --path /Music "$HOME/media/music" https://cloud.example.com

The client prompts for the password. You can use an app password from your Nextcloud account’s security settings. Do not append a WebDAV endpoint to the server URL; use --path for a remote subfolder.

Run nextcloudcmd without arguments to display its help, or nextcloudcmd --version to display its version. Options with values accept both --option value and --option=value.

Options

Parameter	Default	Description
`--path <path>`	Server root	Synchronize a remote subfolder, for example `/Documents`.
`--user <user>`, `-u <user>`	See credentials below	Login name. Overrides the username in the server URL.
`--password <password>`, `-p <password>`	See credentials below	Password or app password. Overrides the password in the server URL. Command-line passwords may be visible in process listings and shell history.
`-n`	Not set	Read credentials from a matching host or default entry in `.netrc`. These replace credentials supplied in the URL or with `--user` and `--password`.
`--non-interactive`	Not set	Do not prompt for credentials. Read missing credentials from `NC_USER` and `NC_PASSWORD`.
`--silent`, `-s`	Not set	Suppress Qt log messages. Does not suppress every console message.
`--trust`	Not set	Accept untrusted TLS certificates. Use only for a controlled diagnostic run; normally fix the certificate trust configuration.
`--httpproxy <url>`	No explicit proxy	Set an HTTP proxy using `http://hostname:port`. This option does not parse proxy credentials in the URL.
`--exclude <file>`	System exclude list	Add an exclude list. The file must exist. Pattern anchoring depends on its filename; see Exclude lists.
`--exclude-anchored <file>`	Not set	Add an exclude list with patterns anchored at the sync root, regardless of the filename.
`--unsyncedfolders <file>`	Not set	Read remote folders to exclude from synchronization, one relative path per line. Empty lines and lines starting with `#` are ignored.
`--max-sync-retries <number>`	`3`	Maximum number of follow-up runs when the sync engine requests another sync. This is not a general retry count for every failed request.
`--uplimit <number>`	`0` KB/s	Upload speed limit in KB/s (1000 bytes per second). Zero means unlimited.
`--downlimit <number>`	`0` KB/s	Download speed limit in KB/s (1000 bytes per second). Zero means unlimited.
`-h`	Hidden files included	Include hidden files. This is already the default; `-h` does not display help.
`--logdebug`	Not set	Enable Nextcloud debug logging and send log output to standard output.
`--confdir <directory>`	Standard location	Use a different configuration directory. Does not make the one-run sync inherit all desktop sync settings.
`--version`, `-v`	Not requested	Display version information and exit. Run this option without the directory and server arguments.

Credential handling

Credentials are read in this order:

Username and password in the server URL, if supplied.
--user and --password, which replace the corresponding URL values.
A matching host or default .netrc entry when -n is used, which replaces both values.
Prompts for any missing values, or the environment variables below when --non-interactive is used.

Prefer a password prompt or a protected .netrc file over putting passwords in a command or URL.

Parameter	Default	Description
`NC_USER`	Unset	Username fallback for a one-run sync with `--non-interactive`. Only used if no username was supplied by the preceding methods.
`NC_PASSWORD`	Unset	Password fallback for a one-run sync with `--non-interactive`. Only used if no password was supplied by the preceding methods.

These variables do not supply credentials for the account setup mode below. For transfer overrides shared with the desktop sync engine, see Environment variables. nextcloudcmd uses an initial chunk size of 100 MiB, a minimum of 5 MB, a maximum of 5 GB, and 6 parallel jobs unless overridden by those variables. It does not read the desktop app’s chunk-size settings from nextcloud.cfg.

Exclude lists

The client loads the system exclude list when available. You can add your own list with --exclude or --exclude-anchored. A missing explicitly supplied file is an error.

With --exclude, a file named sync-exclude.lst uses the sync root for pattern matching. Other filenames can use the exclude file’s directory as the base. Use --exclude-anchored when the filename and location should not affect matching.

Write one pattern per line. Wildcards are supported, for example:

*.tmp
._*
Thumbs.db

Account setup

nextcloudcmd can also save an account for use by the desktop app. The presence of --userid selects this mode; omit the positional local directory and server URL used for a one-run sync. The command exits after setup completes.

Parameter	Default	Description
`--userid <user>`	Required	User ID for the account to create. Use together with `--serverurl`.
`--serverurl <url>`	Required	Base URL of the Nextcloud server, for example `https://cloud.example.com`.
`--apppassword <password>`	Not set	App password for the account. If omitted, the account is saved and you must log in from the desktop app later.
`--localdirpath <path>`	Suggested folder	Local sync folder. If omitted, use the folder suggested by the setup wizard. An existing folder must be empty. Ignored when macOS File Provider mode is enabled.
`--remotedirpath <path>`	`/`	Remote folder for the new classic sync connection. Applies when a local sync folder is created.
`--isvfsenabled <0\|1>`	`0`	Use `1` to request virtual files for the new classic sync folder, where supported, or `0` to download files. This does not enable macOS File Provider mode.

For example, save an account and log in from the desktop app afterward:

nextcloudcmd --userid carla --serverurl https://cloud.example.com --localdirpath "$HOME/Nextcloud"