Cloud Sync

Synchronize your vault across multiple devices using rclone. This enables seamless access to your credentials from different computers (e.g., dual-boot setups, work/home machines).

Overview

Pass-CLI integrates with rclone to sync your vault directory to cloud storage providers. The sync feature:

Pulls the latest vault from the cloud before any operation (once per session)
Pushes changes to the cloud after write operations (add, update, delete)
Works offline - operations continue if sync fails (with warning)
Supports 70+ cloud providers via rclone (Google Drive, Dropbox, OneDrive, S3, etc.)

How Sync Works

┌─────────────┐     pull (on first use)      ┌─────────────┐
│   Device A  │ ◄──────────────────────────► │   Cloud     │
│  (Windows)  │                              │  Storage    │
└─────────────┘     push (after writes)      └─────────────┘
                                                    ▲
                                                    │
┌─────────────┐     pull (on first use)             │
│   Device B  │ ◄───────────────────────────────────┘
│   (Linux)   │     push (after writes)
└─────────────┘

Session-aware sync: Pull only happens once per CLI session to avoid unnecessary network calls. Push happens immediately after every write operation.

Prerequisites

1. Install rclone

Windows (Scoop):

scoop install rclone

Windows (Chocolatey):

choco install rclone

macOS:

brew install rclone

Linux (Debian/Ubuntu):

sudo apt install rclone

Linux (Arch):

sudo pacman -S rclone

Verify installation:

rclone version

2. Configure a Remote

Configure rclone with your cloud provider. Example for Google Drive:

rclone config

Follow the interactive prompts:

Choose n for new remote
Name it (e.g., gdrive)
Select your provider (e.g., drive for Google Drive)
Follow provider-specific OAuth flow
For Google Drive, select scope 3 (drive.file) for minimal permissions

Test the remote:

# List remote contents
rclone ls gdrive:

# Create a test directory
rclone mkdir gdrive:.pass-cli

Enabling Sync

There are two ways to enable sync on your vault:

Option 1: During Vault Initialization (Recommended for New Vaults)

When running pass-cli init to create a new vault, you’ll be offered the option to enable cloud sync:

pass-cli init

# ... after vault creation ...
Enable cloud sync? (requires rclone) (y/n) [n]: y

Enter your rclone remote path.
Examples:
  gdrive:.pass-cli         (Google Drive)
  dropbox:Apps/pass-cli    (Dropbox)
  onedrive:.pass-cli       (OneDrive)

Remote path: gdrive:.pass-cli

The sync configuration is automatically saved to your config file.

Option 2: On an Existing Vault

To enable sync on a vault you’ve already created, use the sync enable command:

pass-cli sync enable

This command:

Checks that your vault exists
Verifies rclone is installed and configured
Prompts you to enter your rclone remote path
Tests connectivity to the remote
Warns if the remote already contains files (use --force to overwrite)
Performs an initial push of your vault to the remote
Saves the configuration automatically

Examples:

# Enable sync interactively
pass-cli sync enable

# Force overwrite if remote already has files
pass-cli sync enable --force

Flags:

Flag	Description
`--force`	Overwrite remote if it already contains vault files

Manual Configuration

You can also enable sync by editing your config file directly (~/.pass-cli/config.yml):

sync:
  enabled: true
  remote: "gdrive:.pass-cli"  # Format: <remote-name>:<path>

Configuration Options

Option	Type	Default	Description
`enabled`	bool	`false`	Enable/disable sync
`remote`	string	`""`	rclone remote and path (e.g., `gdrive:.pass-cli`)

Remote Path Format

The remote field uses rclone’s remote path format:

# Google Drive
remote: "gdrive:.pass-cli"

# Dropbox
remote: "dropbox:Apps/pass-cli"

# OneDrive
remote: "onedrive:Documents/pass-cli"

# S3-compatible storage
remote: "s3:my-bucket/pass-cli"

# SFTP server
remote: "myserver:/home/user/.pass-cli"

Usage

Once configured, sync happens automatically:

# First command in session - pulls from cloud
pass-cli list

# Subsequent reads - no sync (already pulled this session)
pass-cli get github

# Write operations - push to cloud after completion
pass-cli add newservice --username user --password pass
# Output: [sync] Pushed changes to remote

Manual Sync

Sync is automatic, but you can manually trigger it by restarting your terminal session or using rclone directly:

# Manual pull
rclone sync gdrive:.pass-cli ~/.pass-cli

# Manual push
rclone sync ~/.pass-cli gdrive:.pass-cli

Portable Audit Keys

When sync is enabled, pass-cli automatically uses portable audit key derivation. This means:

Audit keys are derived from your master password (not stored in OS keychain)
verify-audit command works on any synced device
Audit log integrity can be verified cross-platform

The audit salt is stored in your vault’s metadata file and syncs with your vault.

How It Works

Master Password + Audit Salt
         │
         ▼ PBKDF2-SHA256 (100k iterations)
         │
    Audit Key
         │
         ▼
   HMAC Signatures (audit log entries)

This replaces the default keychain-based audit key storage when sync is enabled.

Dual-Boot Setup Example

Perfect for users who dual-boot between Windows and Linux:

1. Configure rclone on both OSes (with same remote name):

# On Windows
rclone config
# Create remote named "gdrive"

# On Linux
rclone config
# Create remote named "gdrive" (same name, same account)

2. Enable sync on both OSes (~/.pass-cli/config.yml):

sync:
  enabled: true
  remote: "gdrive:.pass-cli"

3. Initialize vault on one OS:

# On Windows
pass-cli init
pass-cli add github --username myuser --password mypass
# Vault syncs to cloud

4. Use on other OS:

# On Linux - first use pulls vault from cloud
pass-cli list
# Shows: github

Connecting to an Existing Synced Vault

If you already have pass-cli set up with sync on another device and want to connect from a new machine, use the guided flow during initialization:

Important: When running pass-cli init, select “Connect to existing synced vault” instead of “Create new vault” to download your existing vault instead of creating a new one.

Quick Setup

When running pass-cli init on a new machine, you’ll be prompted:

pass-cli init

Is this a new installation or are you connecting to an existing vault?

  [1] Create new vault (first time setup)
  [2] Connect to existing synced vault (requires rclone)

Enter choice (1/2) [1]: 2

🔗 Connect to existing synced vault

Enter your rclone remote path where your vault is stored.
Examples:
  gdrive:.pass-cli         (Google Drive)
  dropbox:Apps/pass-cli    (Dropbox)
  onedrive:.pass-cli       (OneDrive)

Remote path: gdrive:.pass-cli
✓ Vault downloaded
✓ Vault unlocked successfully

✅ Connected to synced vault!

Step-by-Step Manual Setup

1. Install pass-cli and rclone on the new machine:

# macOS
brew tap arimxyer/homebrew-tap && brew install pass-cli rclone

# Windows
scoop bucket add arimxyer https://github.com/arimxyer/scoop-bucket
scoop install pass-cli rclone

# Linux
# Install pass-cli from releases, then:
sudo apt install rclone

2. Configure rclone with the same cloud account:

rclone config
# Create remote with the SAME name as your other device (e.g., "gdrive")
# Log in with the SAME cloud account

3. Verify you can see your existing vault:

rclone ls gdrive:.pass-cli
# Should show: vault.enc, vault.enc.meta.json, etc.

4. Create the pass-cli config file manually:

# Create config directory
mkdir -p ~/.pass-cli

# Create config file
cat > ~/.pass-cli/config.yml << 'EOF'
sync:
  enabled: true
  remote: "gdrive:.pass-cli"
EOF

On Windows (PowerShell):

mkdir -Force ~\.pass-cli
@"
sync:
  enabled: true
  remote: "gdrive:.pass-cli"
"@ | Out-File -FilePath ~\.pass-cli\config.yml -Encoding UTF8

5. Run any pass-cli command - it will pull your vault:

pass-cli list
# Output:
# Syncing vault...
# Enter master password: ****
# github
# aws-prod
# ...

Use your existing master password from the original device.

What Happens Behind the Scenes

pass-cli sees sync is enabled
Calls rclone sync <remote> <local> (pull)
Your vault downloads from cloud to ~/.pass-cli/
pass-cli prompts for master password
Vault unlocks with your existing password
You’re connected!

Common Mistakes

Mistake	Result	Fix
Running `pass-cli init` first	Creates new vault, may overwrite cloud on push	Delete local vault, follow steps above
Different rclone remote name	Sync can’t find remote	Use same remote name on all devices
Wrong cloud account	Downloads empty or different vault	Reconfigure rclone with correct account
Typo in remote path	“Remote not found” error	Check with `rclone listremotes`

Conflict Handling

Pass-CLI uses rclone’s sync behavior which overwrites the destination with the source. This means:

Pull: Cloud overwrites local (ensures you have latest)
Push: Local overwrites cloud (your changes take precedence)

To avoid conflicts:

Always use the same device for a session
Don’t run pass-cli simultaneously on multiple devices
If unsure, manually check with rclone ls <remote> before operations

Offline Operation

Sync failures don’t block operations:

# If offline or cloud unreachable
pass-cli add service --username user --password pass

# Output:
# Warning: sync push failed: <error details>
# Credential 'service' added successfully

Your local vault is updated successfully. Changes sync on next successful push.

Troubleshooting

Sync Not Working

Verify rclone is installed:
```
rclone version
```
Test remote connectivity:
```
rclone ls gdrive:.pass-cli
```
Check configuration:
```
pass-cli config validate
```

Verify sync is enabled:

# ~/.pass-cli/config.yml
sync:
  enabled: true      # Must be true
  remote: "gdrive:.pass-cli"  # Must not be empty

“rclone not found” Warning

Install rclone and ensure it’s in your PATH:

# Check if rclone is in PATH
which rclone    # Linux/macOS
where rclone    # Windows

Permission Denied Errors

Ensure your rclone remote has write permissions:

# Test write access
echo "test" > /tmp/test.txt
rclone copy /tmp/test.txt gdrive:.pass-cli/
rclone ls gdrive:.pass-cli/

Audit Verification Fails After Sync

If verify-audit fails on a synced device:

Ensure you’re using the same master password on all devices
Check that the vault metadata file (.meta.json) synced correctly
The audit salt must be present in metadata for portable key derivation

Slow Sync Operations

For large vaults or slow connections:

# Check what will be synced without transferring
rclone sync ~/.pass-cli gdrive:.pass-cli --dry-run

# Show transfer progress
rclone sync ~/.pass-cli gdrive:.pass-cli --progress

Security Considerations

What Gets Synced

The entire vault directory is synced, including:

vault.enc - Encrypted vault (AES-256-GCM)
vault.enc.meta.json - Vault metadata (audit salt, timestamps)
audit.log - Audit log (HMAC-signed entries)
Backup files (if present)

What Stays Local

Master password (never stored)
Keychain entries (OS-specific)
Session state (in-memory only)

Cloud Storage Security

Your vault is already encrypted with AES-256-GCM before sync. The cloud provider only sees encrypted data. However:

Use a strong master password
Enable 2FA on your cloud account
Consider using end-to-end encrypted providers (e.g., rclone crypt)

Additional Encryption Layer (Optional)

For extra security, use rclone’s crypt remote:

# Create encrypted remote on top of cloud storage
rclone config
# Choose 'crypt' type
# Set remote to "gdrive:.pass-cli"
# This adds another encryption layer