📖 Introduction

pcloud-cli brings everyday pCloud operations to your terminal. Browse and manage files, recover what you deleted from the trash, and roll a file back to a previous version — all without leaving the command line.

It authenticates once and stores the token locally. A single environment variable lets you bypass stored credentials entirely for CI and scripted contexts.

✨ Features

• Folder operations — ls, stat, mkdir, rmdir, and file copy / move / rename / delete from the terminal.
• Trash recovery — list deleted files and restore them by file ID.
• Rewind & revisions — browse a file's version history and restore an earlier version to any destination.
• Local sync inspection — read the pCloud Drive daemon's own database to find broken sync pairs, and prune orphaned ones the desktop app reports only as a bogus permissions error.
• Sync folder scaffolding — sync add makes the folder on both sides and tells you the two paths to pair, so only the pairing itself stays in the app.
• Machine-readable everywhere — every data-returning command renders for humans by default and emits the raw payload under --json.
• Two ways to log in — email and password by default (no setup, full API access), or browser-based OAuth 2.0 if you would rather the CLI never handled your password. Tokens are stored at ~/.config/pcloud/tokens.json (mode 0600).
• CI-friendly — set PCLOUD_AUTH or PCLOUD_ACCESS_TOKEN to skip the credential store entirely.
• Regional endpoints — targets the EU API by default; switch with PCLOUD_REGION=us.

📦 Install

npm install -g @kud/pcloud-cli

Requires Node.js 24 or newer (the sync commands use the built-in node:sqlite). The binary is exposed as pcloud.

🚀 Quick start

Authenticate once, then run any command:

pcloud login
pcloud                    # the browser
pcloud ls /
pcloud doctor             # what is wrong, and which command fixes it

See The browser for the full-screen client, Authentication for both login methods and when to choose each, Trash & restore and Rewind & versions for recovery workflows, Shares for folder sharing in both directions, Local sync inspection and Client settings for the desktop app's own database, and doctor when something is wrong and you want to be told what.

⚙️ Configuration

Neither client variable is needed for the default pcloud login. When either token variable is set, no stored credentials are read or written; PCLOUD_AUTH takes precedence, since a session token reaches more of the API.