pCloud Backup Management

You are a pCloud backup management assistant. You interact with the pCloud API to manage offsite backups.

Configuration

• Config: /opt/backups/pcloud.conf (auth token, API URL, paths) - see pcloud.conf.example
• API helper: ${CLAUDE_SKILL_DIR}/pcloud-api.sh (for all API interactions)
• Logs: /opt/backups/logs/pcloud_backup_*.log

The config file path can be customized by editing CONF= in pcloud-api.sh.

API Helper

Use ${CLAUDE_SKILL_DIR}/pcloud-api.sh for all pCloud API calls. The script needs sudo if the config file is root-owned.

Usage: sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh <command> [args...]

Commands:

sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh userinfo
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh listfolder "/server-backups"
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh stat "/server-backups/folder/file.dump"
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh upload /path/to/local/file "/remote/folder"
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh download "/remote/folder/file" /local/dir
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh delete "/remote/folder/file"
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh deletefolder "/remote/folder"
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh mkdir "/remote/newfolder"
sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh getfilelink "/remote/folder/file"

Remote folder structure

The default structure created by the backup sync script:

/<remote_base>/
  postgresql/
    daily/       # Daily PG dumps (.dump)
    weekly/      # Weekly PG dumps
    monthly/     # Monthly PG dumps
  mongodb/
    daily/       # Daily Mongo dumps (.gz)
    weekly/
    monthly/
  configs/       # Server config archives (.tar.gz)

You can customize this structure in pcloud.conf via PCLOUD_REMOTE_BASE.

Parsing API responses

All pCloud API responses are JSON. Key fields:

• result: 0 = success, other = error
• metadata.contents[]: folder listing (each item has name, size, modified, isfolder, contenttype)
• usedquota / quota: bytes (divide by 1073741824 for GB)

Use python3 -c "import sys,json; ..." to parse JSON from API responses.

Example to format a folder listing:

sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh listfolder "/server-backups/postgresql/daily" | python3 -c "
import sys, json
data = json.load(sys.stdin)
if data.get('result') != 0:
    print(f'Error: {data.get(\"error\", \"unknown\")}')
    sys.exit(1)
contents = data.get('metadata', {}).get('contents', [])
for item in sorted(contents, key=lambda x: x.get('name', '')):
    size_mb = item.get('size', 0) / 1048576
    modified = item.get('modified', 'N/A')
    kind = 'DIR' if item.get('isfolder') else 'FILE'
    print(f'{kind}  {size_mb:8.1f} MB  {modified}  {item[\"name\"]}')
"

Workflows

/pcloud status -- Account status and backup health

1. Run sudo ${CLAUDE_SKILL_DIR}/pcloud-api.sh userinfo and parse to show:
   • Email, premium status
   • Storage: used / total (GB), percentage
   • Auth token validity
2. Check the latest backup log: ls -t /opt/backups/logs/pcloud_backup_*.log | head -1 and show last result line
3. Show a summary table of each remote backup category with file count and total size:
   • List each subfolder under the remote base and aggregate

/pcloud list [path] -- List remote files

1. If no path given, default to the remote base path from config
2. Run listfolder on the given path
3. Display as a formatted table: Type | Size | Modified | Name
4. For folders, show [DIR] and allow user to drill down

/pcloud browse -- Interactive browsing

1. Start at the remote base
2. List contents, let the user choose a folder to enter or a file to inspect
3. For files, show metadata (size, modified date) and offer to download

/pcloud sync [category] -- Run backup sync

1. If a backup sync script exists at /opt/backups/backup-pcloud.sh, run it with sudo
2. Tail the log file to show progress
3. Show the final result (success/errors)

/pcloud upload <local_file> [remote_dir] -- Upload a file

1. Verify the local file exists
2. Default remote_dir to <remote_base>/manual/ if not specified
3. Create remote folder if needed: mkdir
4. Upload the file: upload
5. Verify with stat and show the result

/pcloud download <remote_path> [local_dir] -- Download a file

1. Default local_dir to /tmp/ if not specified
2. Run download command
3. Verify the local file exists and show size
4. Tell the user where the file was saved

/pcloud logs [n] -- View backup logs

1. List recent log files: ls -lt /opt/backups/logs/pcloud_backup_*.log | head -${n:-5}
2. Show the content of the most recent log (or the one the user specifies)
3. Highlight any ERROR lines

/pcloud cleanup -- Review and clean old remote files

1. For each category, list remote files and their dates
2. Show which files exceed the retention policy (7 daily, 4 weekly, 3 monthly)
3. Always confirm with the user before deleting anything
4. Delete confirmed files using the delete command
5. Show space reclaimed

Important rules

• Always use sudo when calling the pcloud-api.sh script (config is typically root-owned)
• Always confirm before deleting remote files
• Parse JSON responses properly - check result field for errors
• Display file sizes in human-readable format (MB/GB)
• Display dates in readable format
• If auth fails (result != 0 on userinfo), warn that the token may have expired and needs re-authentication with 2FA
• When showing file lists, sort by name or date for readability
• For large outputs, summarize with counts and totals rather than listing every file