v0.1.0 · MIT

pcloud-cli

Manage your pCloud files from the terminal — restore deleted files, browse version history, and recover previous states in seconds.

View on npm GitHub ↗

npm install -g @kud/pcloud-cli

v0.1.0

Latest

Commands

TypeScript

MIT

Licence

Why pcloud-cli

Features

Everything you need to manage pCloud files without leaving the terminal.

🔐

OAuth 2.0 Login

One-time browser-based setup. Your token is saved securely to ~/.config/pcloud/tokens.json — no password ever touches the CLI.

🗑️

Trash Management

List every file in your pCloud trash with deletion timestamps and sizes, then restore any of them by file ID.

⏪

Rewind Recovery

Browse the full version history of any file path and restore a previous version to any destination you choose.

🌍

EU & US Routing

Automatically uses the correct API hostname returned at login — works for both EU (eapi.pcloud.com) and US accounts.

⚡

Zero Re-auth

Stored tokens are reused across sessions. Optionally bypass storage entirely with the PCLOUD_ACCESS_TOKEN env var.

🏷️

Strict TypeScript

Fully typed source with strict mode enabled. Compiles to CommonJS for broad Node.js compatibility from v20+.

Get going fast

Quick Start

Install, authenticate once, then manage your files.

# Install globally
npm install -g @kud/pcloud-cli

# One-time OAuth setup — opens your browser
pcloud login
✓ Authentication successful!
🎉 Setup complete! Token saved to ~/.config/pcloud/tokens.json

# List files in your trash
pcloud list-trash
┌──────────┬──────────────────────┬──────────────────────────┐
│ File ID  │ Name                 │ Deleted                  │
├──────────┼──────────────────────┼──────────────────────────┤
│ 12345    │ report-final.pdf     │ 2026-04-15 09:12         │
│ 67890    │ old-invoice.xlsx     │ 2026-04-10 14:30         │
└──────────┴──────────────────────┴──────────────────────────┘

# Restore a file from trash
pcloud restore-trash 12345
✓ File 12345 restored successfully.

Commands

CLI Reference

All commands are available as pcloud <command> after a global install.

pcloud login Initiate the OAuth 2.0 flow — opens your browser, exchanges the code, and saves the token to ~/.config/pcloud/tokens.json.

pcloud logout Remove the stored token and sign out of the CLI.

pcloud list-trash List all files currently in your pCloud trash, with file ID, name, path, size, and deletion time.

pcloud restore-trash <fileid> Restore a deleted file from trash back to its original location using its numeric file ID.

pcloud list-rewind <path> List all rewind (version history) events for a given file path, showing each version's file ID and timestamp.

pcloud restore-rewind <fileid> <destination> Restore a specific version of a file from rewind history to a destination path you specify.

Configuration

Token storage is automatic after pcloud login. The following env vars let you override or extend the defaults.

Variable	Required	Default	Description
`PCLOUD_CLIENT_ID`	For login only	`—`	OAuth application client ID from my.pcloud.com.
`PCLOUD_CLIENT_SECRET`	For login only	`—`	OAuth application client secret.
`PCLOUD_ACCESS_TOKEN`	No	`—`	Bypass stored tokens entirely. When set, this token is used directly and no file is read or written.