lkn
/
pcloudcc-lneely
mirror of https://github.com/lneely/pcloudcc-lneely.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
pcloudcc-lneely/doc/USAGE.md

5.9 KiB
Raw Permalink Blame History

pcloudcc usage

Getting Help

Terminal command is pcloudcc and -h option prints short options description.

pcloudcc -h

New Options

Cache Size Management

By default, the cache is limited to 5GB. You can adjust this with --cache-size (value in GB):

# Set cache to 10GB
pcloudcc -u example@myemail.com -d --cache-size 10

# Set to 1GB for limited storage systems
pcloudcc -u example@myemail.com -d --cache-size 1

Custom Log Path

By default, logs are written to ~/.pcloud/debug.log. You can specify a custom path:

# System-wide log (requires permissions)
pcloudcc -u example@myemail.com -d --log-path /var/log/pcloudcc.log

# Custom user log
pcloudcc -u example@myemail.com -d --log-path ~/my-pcloud.log

See LOG-MANAGEMENT.md for log rotation configuration.

Log Level Control

By default, the logging level is set to INFO. You can adjust verbosity with --log-level:

# Minimal logging (errors only)
pcloudcc -u example@myemail.com -d --log-level ERROR

# Quiet mode (no logging)
pcloudcc -u example@myemail.com -d --log-level NONE

# Detailed logging for troubleshooting
pcloudcc -u example@myemail.com -d --log-level DEBUG

Available levels (from least to most verbose):

  • NONE - Disable all logging
  • ERROR - Only critical errors
  • WARNING - Errors and warnings
  • INFO - Normal operation info (default)
  • NOTICE - Informational notices
  • DEBUG - Detailed debug information

Filesystem Events Log

Enable a separate log containing only filesystem events (no debug messages):

pcloudcc -u example@myemail.com -d --fs-event-log ~/.pcloud/fs-events.log

Event format: <timestamp> <event_type> <path>

Event types:

  • file created, file modified, file deleted, file downloaded
  • file moved <oldpath> -> <newpath>
  • folder created, folder deleted
  • folder moved <oldpath> -> <newpath>

Example log entries:

Wed, 12 Nov 2025 05:24:23.032 +0000 file deleted /tmp/xxx
Wed, 12 Nov 2025 05:24:47.861 +0000 folder moved /tmp/test2 -> /tmp/test3
Wed, 12 Nov 2025 05:25:10.445 +0000 file created /tmp/newfile.txt

See LOG-MANAGEMENT.md for monitoring scripts and log rotation setup.

FUSE Mount Options

Pass custom FUSE mount options with --fuse-opts:

# Allow other users to access the mount
pcloudcc -u example@myemail.com -d --fuse-opts allow_other

# Multiple options (comma-separated)
pcloudcc -u example@myemail.com -d --fuse-opts allow_other,allow_root

# Set custom permissions
pcloudcc -u example@myemail.com -d --fuse-opts default_permissions,uid=1000,gid=1000

Common FUSE options:

  • allow_other - Allow all users to access files (requires /etc/fuse.conf setting)
  • allow_root - Allow root to access files
  • default_permissions - Enable kernel permission checking
  • uid=N, gid=N - Set file owner/group
  • umask=OCTAL - Set file permission mask

See man fuse for complete list of available options.

First Use

Start the service in the foreground using the -p switch to enter your password, and the -s switch to save the password to the database. Verify that file system starts and mounts normally after the

pcloudcc -u example@myemail.com -p -s

Optionally specify your own mount point.

pcloudcc -u example@myemail.com -p -s -m /path/to/mountpoint

Registration (UNTESTED)

If you don't have existing user use -n switch to register new user:

pcloudcc -u example@myemail.com -p -s -n

Notice that a new user may take a while to mount. Please, be patient.

Run as Daemon

Daemon mode (-d) is the recommended way to run pcloudcc in production. Running in foreground mode can cause FUSE filesystem errors and crashes if interrupted.

If you have saved your password, then you can run pcloudcc as a background daemon:

pcloudcc -u example@myemail.com -d

With custom mount point, cache size, and log path:

pcloudcc -u example@myemail.com -d -m /mnt/pcloud --cache-size 10 --log-path /var/log/pcloudcc.log

Verify the filesystem is mounted when the daemon starts:

mount | grep pCloud
ps aux | grep pcloudcc

Stopping the Daemon

To stop the daemon gracefully, use one of these methods:

# Graceful shutdown (recommended)
pkill -TERM pcloudcc

# Or use the command prompt
pcloudcc -k
# Then type: finalize

Important: Do NOT use kill -9 or interrupt with Ctrl+C, as this can cause filesystem corruption.

Available Signals

  • SIGTERM / SIGINT: Gracefully shut down the daemon
  • SIGHUP: Terminate the daemon (exits the process)
  • SIGUSR1: Dump internal debugging information (debug builds only)
  • SIGUSR2: Reopen log files for rotation

Log Rotation with SIGUSR2

The daemon responds to SIGUSR2 by reopening both the debug log and fs-events log (if enabled). This allows safe log rotation:

# Manual log rotation
mv ~/.pcloud/debug.log ~/.pcloud/debug.log.old
pkill -SIGUSR2 pcloudcc

# With fs-events log
mv ~/.pcloud/fs-events.log ~/.pcloud/fs-events.log.old
pkill -SIGUSR2 pcloudcc

For automatic log rotation with logrotate, see LOG-MANAGEMENT.md.

Command Prompt

Use the command prompt to interact with a running daemon.

pcloudcc -k

Command Reference:

  help(?): Show this help message
  crypto(c):
    start <crypto pass>: Unlock crypto folder
    stop: Lock crypto folder
  sync(s):
    list(ls): List sync folders
    add <localpath> <remotepath>: Add sync folder
    remove(rm) <folderid>: Remove sync folder
  finalize(f): Kill daemon and quit
  quit(q): Exit this program

Note. Command line arguments that include special characters (e.g., the crypto start password or paths with spaces) must be quoted or escaped. In other words, instead of:

startcrypto Str0ng p4$$word 4 great jUSTicE!

One must now type, for example:

c start 'Str0ng p4$$word 4 great jUSTicE!'

If the password includes quotes for some reason, then those characters must be escaped properly.