Proton Drive CLI

End-to-end encrypted CLI for Proton Drive with Git LFS bridge support, powered by the official @protontech/drive-sdk.

Documentation

📚 Complete Documentation with:

• TypeScript API Reference - Full TSDoc API documentation
• Architecture & Guides - Setup, security, operations

Installation

corepack enable
yarn install
yarn build

For local development, invoke the CLI directly with node dist/index.js.

Credential Providers

Passwords are never accepted via CLI flags or environment variables. This prevents leaks via ps, /proc/pid/environ, and shell history.

Git Credential Manager (recommended)

Uses the system credential helper (macOS Keychain, Windows Credential Manager, Linux Secret Service) via git credential fill.

# Store credentials in the system credential helper

proton-drive-cli credential store -u [email protected]

# Verify credentials are stored

proton-drive-cli credential verify

# Login using stored credentials

proton-drive-cli login --credential-provider git

# Use with any command

proton-drive-cli ls / --credential-provider git

# Remove stored credentials

proton-drive-cli credential remove -u [email protected]

pass-cli (Git LFS integration)

When used through proton-git-lfs, the Go adapter resolves credentials via pass-cli and spawns proton-drive-cli bridge directly, passing credentials over stdin. Do not run proton-drive-cli login manually in this mode.

pass-cli → Go adapter → proton-drive-cli bridge (stdin, memory only)

Piped stdin (scripted usage)

For CI or scripted environments where git-credential is not available:

printf '%s' 'password' | proton-drive-cli login -u [email protected] --password-stdin
printf '%s' 'password' | proton-drive-cli credential store -u [email protected] --password-stdin

Usage

Authentication

# Login with git-credential (recommended)

proton-drive-cli login --credential-provider git

# Login with piped password

printf '%s' 'your-password' | proton-drive-cli login -u [email protected] --password-stdin

# Check authentication status

proton-drive-cli status

# Logout

proton-drive-cli logout

Session tokens (no passwords) are stored in ~/.proton-drive-cli/session.json with 0600 permissions. Tokens are refreshed automatically on HTTP 401 and Proton error code 9101.

CAPTCHA: If CAPTCHA verification is required during login, the CLI guides you through the semi-automated token extraction process.

File Operations

# List files

proton-drive-cli ls /
proton-drive-cli ls /Documents --long

# Upload files

proton-drive-cli upload ./file.pdf /Documents
cat data.json | proton-drive-cli upload - /Documents --name data.json

# Download files

proton-drive-cli download /Documents/file.pdf ./file.pdf

# Create folders

proton-drive-cli mkdir /Documents Projects

# Show file/folder metadata

proton-drive-cli info /Documents/file.pdf

# Stream file contents to stdout

proton-drive-cli cat /Documents/file.txt

# Move or rename files/folders

proton-drive-cli mv /Documents/old-name.pdf /Documents/new-name.pdf

# Remove files/folders

proton-drive-cli rm /Documents/old-file.pdf
proton-drive-cli rm /Documents/old-file.pdf --permanent

Global Options

| Flag | Description | | ----------------------- | ------------------------------------------------- | | -d, --debug | Enable debug output with full stack traces | | --verbose | Show detailed output (spinners, progress, tables) | | -q, --quiet | Suppress all non-error output | | -v, --version | Display version number | | --credential-provider | Credential source: git or default (stdin) |

Developer Documentation

See docs/ for detailed documentation:

• Architecture — Components, data flow, SDK adapter layer
• Credential Security — Credential flows, threat model, trust boundaries
• Configuration — Environment variables, session management

When docs disagree, runtime behavior and tests win.

Testing

yarn test                        # Run all tests (fully mocked)
yarn test --no-cache             # Without cache
npx jest src/sdk/                # SDK adapter tests only
npx jest src/cli/e2e.test        # E2E CLI tests

All tests are fully mocked and CI-safe — no Proton credentials required.

License

MIT