A privacy-first, local-first password manager with cross-platform synchronization.
- π Privacy-First: All encryption happens locally, zero-knowledge architecture
- π Cross-Platform: macOS, Linux, Windows support
- π‘ Local-First: SQLite database stored locally, cloud sync is optional backup
- π Strong Crypto: Argon2id key derivation, AES-256-GCM encryption
- π Clipboard Integration: Secure clipboard with auto-clear
- π Cloud Sync: iCloud Drive, Dropbox, Google Drive, OneDrive, WebDAV, SFTP
- π€ AI Integration: MCP (Model Context Protocol) support for AI assistants
brew tap OpenKeyring/homebrew-tap brew install OpenKeyring/homebrew-tap/ok
cargo install keyring-cli
# Clone the repository git clone https://github.com/open-keyring/keyring-cli.git cd keyring-cli # Build the project cargo build --release # Install the binary cargo install --path .
First-Time Initialization
When you run your first command, OpenKeyring automatically initializes:
- Creates the database at
~/.local/share/open-keyring/passwords.db - Creates the keystore at
~/.config/open-keyring/keystore.json - Prompts for a master password
- Generates and displays a 24-word BIP39 recovery key
# First command triggers initialization ok generate --name "github" --length 16 # You'll see: # π Enter master password: [your password] # π Recovery Key (save securely): word1 word2 word3 ... word24 # β Password generated successfully
Recovery Key
The recovery key is a 24-word BIP39 mnemonic phrase that serves as a backup to your master password.
- When to use: If you forget your master password or need to restore access on a new device
- How to save: Write it down on paper and store securely. Never store it digitally in plain text.
- Security: The recovery key is only shown once during initialization. If lost, data cannot be recovered.
Basic Usage
# Generate a password ok generate --name "github" --length 16 # List all passwords ok list # Show a password ok show "github" --copy # Update a password ok update "github" --password "new_password" # Search passwords ok search "github" # Delete a password ok delete "github" --confirm
# Generate passwords ok generate --name "service" --length 16 ok generate --name "memorable" --memorable --words 4 ok generate --name "pin" --pin --length 6 # List records ok list ok list --type "password" --tags "work" ok list --limit 10 # Show records ok show "service" ok show "service" --show-password ok show "service" --copy # Update records ok update "service" --password "new_pass" ok update "service" --username "user@domain.com" --url "https://example.com" # Delete records ok delete "service" --confirm ok delete "service" --confirm --sync # Search ok search "github" ok search "api" --type "api_credential"
# Password health check ok health --weak --leaks --duplicate # Mnemonic (crypto wallet) ok mnemonic --generate 12 --name "wallet" ok mnemonic --validate "word1 word2 word3..." # Device management ok devices ok devices remove "device-id"
Manual Sync
Sync your passwords across devices using cloud storage:
# Preview changes (dry run) ok sync --dry-run # Full sync ok sync --full # Check sync status ok sync --status # Sync with specific provider ok sync --provider "dropbox"
Supported Sync Providers
- iCloud Drive (default on macOS/iOS)
- Dropbox
- Google Drive
- OneDrive
- WebDAV (self-hosted)
- SFTP (self-hosted)
Sync Configuration
# Enable sync ok config set sync.enabled true # Set provider ok config set sync.provider dropbox # Set remote path ok config set sync.remote_path "/OpenKeyring" # Enable auto-sync ok config set sync.auto_sync true
Configuration
# List all settings ok config list # Set configuration values ok config set "database.path" "/custom/path" ok config set "sync.enabled" "true"
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Single Device (e.g., MacBook) β
β βββββββββββββββ ββββββββββββββββββββ βββββββββββββββ β
β β ok CLI β β OpenKeyring App β β ok CLI β β
β β (Rust) β β (Swift) β β (Rust) β β
β ββββββββ¬βββββββ ββββββββββ¬ββββββββββ ββββββββ¬βββββββ β
β ββββββββββββββββββββ΄ββββββββββββββββββββ β
β β β
β βββββββββββββββββββββββββββ β
β β Crypto & Storage Core β β
β β - Crypto (Argon2id, β β
β β AES-256-GCM) β β
β β - SQLite + WAL β β
β β - Key Hierarchy β β
β βββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Master Password (user-provided)
β Argon2id/PBKDF2 derivation
Master Key (cross-device identical)
β decrypts wrapped keys
βββ Data Encryption Key (DEK) - encrypts actual user data
βββ Recovery Key (24-word BIP39) - emergency access
βββ Device Key (per-device) - enables biometric unlock
Local Database (~/.local/share/open-keyring/passwords.db):
- SQLite with WAL mode for concurrent access
- Each record encrypted individually with AES-256-GCM
- Schema:
records,tags,record_tags,metadata,sync_state
Cloud Sync:
- Per-record JSON files (not full database sync)
- Format:
{id}.jsoncontaining encrypted data + metadata - Supported: iCloud Drive, Dropbox, Google Drive, OneDrive, WebDAV, SFTP
Configuration is stored in YAML format at ~/.config/open-keyring/config.yaml:
database: path: "~/.local/share/open-keyring/passwords.db" encryption_enabled: true crypto: key_derivation: "argon2id" argon2id_params: time: 3 memory: 67108864 # 64MB parallelism: 2 pbkdf2_iterations: 600000 sync: enabled: false provider: "icloud" remote_path: "/OpenKeyring" auto_sync: false conflict_resolution: "newer" clipboard: timeout_seconds: 30 clear_after_copy: true max_content_length: 1024
| Type | Name | Required Fields |
|---|---|---|
password |
Basic Password | name, password |
ssh_key |
SSH Key | name, host, username, private_key |
api_credential |
API Credential | name, api_key |
mnemonic |
Crypto Wallet Mnemonic | name, mnemonic (12/24 words) |
private_key |
Private Key | name, address, private_key |
All types support optional: username, url, notes, tags
# Development build cargo build # Release build cargo build --release # Run tests cargo test # Format code cargo fmt # Lint code cargo clippy
keyring-cli/
βββ src/
β βββ crypto/ # Cryptographic primitives
β βββ db/ # Database layer
β βββ clipboard/ # Platform clipboard integration
β βββ sync/ # Cloud synchronization
β βββ mcp/ # Model Context Protocol
β βββ cli/ # CLI application
βββ tests/ # Test files
βββ Cargo.toml # Dependencies and metadata
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Run
cargo testandcargo clippy - Submit a pull request
- All encryption uses industry-standard algorithms (Argon2id, AES-256-GCM)
- Master password is never stored or transmitted
- Clipboard automatically clears after 30 seconds
- Each record is encrypted with a unique nonce
- Database is locked when not in use
- Regular security audits recommended
This project is licensed under the MIT License - see the LICENSE file for details.
"Master password verification failed"
- Double-check your password (case-sensitive)
- If forgotten, use recovery key to restore access
"Database locked"
- Close other OpenKeyring instances
- Wait a few seconds and try again
"Keystore not found"
- If you have a backup, restore
~/.config/open-keyring/keystore.json - If no backup, you'll need to reinitialize (data loss)
"Sync failed"
- Check internet connection
- Verify sync provider credentials
- Check sync configuration:
ok sync --status - Try dry run first:
ok sync --dry-run
Forgot Master Password
- Use your recovery key to restore access
- If recovery key is also lost, data cannot be recovered (by design)
Lost Device
- Use
ok devicesto list trusted devices - Remove lost device:
ok devices --remove "device-id"
For detailed troubleshooting, see CLI Documentation.
- π§ Email: support@open-keyring.com
- π¬ Discord: Join our community
- π Issues: GitHub Issues
- π Documentation: CLI Documentation
Made with β€οΈ by the OpenKeyring Team