# Smart Password Manager CLI (Rust)
**Command line interface for smart password management built on [smartpasslib](https://github.com/smartlegionlab/smartpasslib-rs). Generate deterministic passwords from secret phrases without storing them. No cloud, no database, no trust required.**
## Overview
Smart Password Manager CLI is a Unix-style command line utility for managing smart passwords — passwords that are regenerated on demand from a secret phrase instead of being stored. It is built on top of the [smartpasslib](https://crates.io/crates/smartpasslib) library and uses the same cryptographic algorithm as the Python, JavaScript, Kotlin, Go and C# implementations.
The application stores only public verification keys, descriptions and lengths. Your secret phrase and the actual passwords are never written to disk. Passwords are recalculated whenever you need them.
The CLI is designed to be scriptable: passwords go to **stdout**, everything else goes to **stderr**, so you can pipe the password into `xclip`, `pbcopy`, `wl-copy`, or any other tool.
**Decentralized by design:** no cloud, no database, no third-party trust required. Your secrets never leave your device.
---
[](https://crates.io/crates/smart-password-manager-cli)
[](https://docs.rs/smart-password-manager-cli)
[](https://github.com/smartlegionlab/smart-password-manager-cli-rs)
[](https://github.com/smartlegionlab/smart-password-manager-cli-rs/blob/master/LICENSE)
[](https://github.com/smartlegionlab/smart-password-manager-cli-rs/)
[](https://github.com/smartlegionlab/smart-password-manager-cli-rs/stargazers)
[](https://github.com/smartlegionlab/smart-password-manager-cli-rs/network/members)
[](https://crates.io/crates/smart-password-manager-cli)
---
## Core Principles
- **Zero-Storage Security**: No passwords or secret phrases are ever stored or transmitted
- **Decentralized Architecture**: No central servers, no cloud dependency, no third-party trust required
- **Deterministic Regeneration**: Passwords are recreated identically from your secret phrase
- **Metadata Only**: Only public keys, descriptions and lengths are stored
- **Scriptable Output**: Passwords go to stdout, diagnostics go to stderr
- **On-Demand Discovery**: Passwords exist only when you generate them
## Key Features
- **Decentralized & Serverless**: No central database, no cloud lock-in, complete user sovereignty
- **No Password Database**: Eliminates password storage completely
- **Deterministic Password Generation**: Same secret + same length = same password, always, on every platform
- **Public Key Verification**: Verify secret knowledge without exposure
- **Unix-friendly**: stdout for passwords, stderr for everything else — pipe anywhere
- **Multiple Secret Input Methods**: interactive prompt, `--secret`, `--secret-stdin`, `SPM_SECRET`
- **JSON Output**: `--json` on `list` and `get` for scripting
- **Clipboard Copy**: `--copy` pipes to `wl-copy`, `xclip`, `xsel` or `pbcopy` when available, and falls back to OSC 52 for compatible terminals
- **Terminal QR**: `--qr` renders the password as a QR code directly in the terminal with ANSI colors — scannable by phone, works on any tty
- **Cross-Platform Data**: Same `passwords.json` format as the Python, JavaScript, Kotlin, Go and C# implementations
- **No Network Access**: Runs entirely offline
---
## Installation
### Option 1: `cargo install`
The simplest way, if you have Rust installed:
```bash
cargo install smart-password-manager-cli
```
Then run:
```bash
smart-password-manager-cli --help
```
### Option 2: Prebuilt binaries
Download the Linux musl binary from GitHub Releases:
```
https://github.com/smartlegionlab/smart-password-manager-cli-rs/releases
```
```bash
chmod +x smart-password-manager-cli-<version>-linux-x86_64-musl
./smart-password-manager-cli-<version>-linux-x86_64-musl --help
```
The musl build is statically linked and runs on any modern Linux distribution without additional dependencies.
### Option 3: One-command install (Linux)
```bash
Installs the binary to `~/.local/bin/`.
### Uninstall
```bash
Your password metadata in `~/.config/smart_password_manager/passwords.json` is never touched. Delete it manually if you want to remove it:
```bash
rm -rf ~/.config/smart_password_manager
```
---
## Quick Usage Guide
### Add an entry
```bash
smart-password-manager-cli add --description "GitHub Account" --length 24
```
Prompts for the secret phrase interactively. Alternatively:
```bash
# from environment (recommended for scripts)
SPM_SECRET='MyStrongSecretPhrase2026!' \
smart-password-manager-cli add --description "GitHub Account" --length 24
# from stdin (safest, never appears in shell history or ps)
```
### Get a password
```bash
# stdout
smart-password-manager-cli get --description "GitHub Account"
# pipe to system clipboard
smart-password-manager-cli get --description "GitHub Account" | pbcopy
# or use --copy (system clipboard tools + OSC 52 fallback)
smart-password-manager-cli get --description "GitHub Account" --copy
# render as QR in the terminal (ANSI colors, scannable by phone)
smart-password-manager-cli get --description "GitHub Account" --qr
# machine-readable
smart-password-manager-cli get --description "GitHub Account" --json
```
### List entries
```bash
smart-password-manager-cli list
smart-password-manager-cli list --json
```
### Edit metadata
```bash
smart-password-manager-cli edit --description "GitHub Account" --new-description "GitHub Personal" --new-length 32
```
### Delete an entry
```bash
smart-password-manager-cli delete --description "GitHub Account"
smart-password-manager-cli delete --description "GitHub Account" --yes
```
### Verify a secret
```bash
smart-password-manager-cli verify --description "GitHub Account"
```
Exits with code `0` if the secret matches, `1` otherwise — usable in scripts.
---
## Command Reference
### Global
```
smart-password-manager-cli --help
smart-password-manager-cli --version
```
### `add`
```
add --description <TEXT> [--length <N>] [--secret <TEXT> | --secret-stdin]
```
### `get`
```
[--copy] [--qr] [--json]
```
### `list`
```
list [--json]
```
### `delete`
```
### `edit`
```
```
### `verify`
```
---
## Secret Phrase Input
The secret phrase can be provided in four ways, tried in this order:
1. `--secret <TEXT>` — direct argument (visible in `ps`, not recommended)
2. `--secret-stdin` — read from stdin (safest for scripts)
3. `SPM_SECRET` environment variable — convenient for CI
4. Interactive prompt via `rpassword` — no echo, default for humans
---
## Clipboard Notes
`--copy` works in interactive terminals:
1. First, it pipes the password to the first available system tool: `wl-copy` (Wayland), `xclip` or `xsel` (X11), `pbcopy` (macOS).
2. If none of those are installed, it falls back to an OSC 52 escape sequence written to stdout. Most modern terminals (`kitty`, `alacritty`, `wezterm`, `iTerm2`, `Windows Terminal`, `GNOME Terminal`, `Konsole`, `tmux` with `set-clipboard on`) and SSH sessions support this.
In non-interactive shells (pipes, CI), `--copy` cannot reach the clipboard. Use a shell pipeline instead:
```bash
smart-password-manager-cli get --description "GitHub Account" | pbcopy
```
---
## QR Notes
`--qr` renders the password as a QR code directly in the terminal, using ANSI background colors so that the QR appears as black modules on a white background. This is what phone scanners expect, and it works even on a bare Linux console without a graphical session.
If the terminal does not support ANSI colors, the QR may not be readable. In that case, pipe the password to a QR encoder on a machine with a graphical session, or use the `--json` flag and process the password elsewhere.
---
## Data Storage
Only public keys, descriptions and lengths are stored, as JSON. The file location follows the standard user data directory convention:
| Linux | `~/.config/smart_password_manager/passwords.json` |
| macOS | `~/.config/smart_password_manager/passwords.json` |
| Windows | `%USERPROFILE%\.config\smart_password_manager\passwords.json` |
Format:
```json
{
"a3f8c1e0b9d2f4a6c8e0b1d3f5a7c9e1b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a1": {
"public_key": "a3f8c1e0b9d2f4a6c8e0b1d3f5a7c9e1b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a1",
"description": "GitHub Account",
"length": 24
}
}
```
**What is NOT stored:**
- Your secret phrase
- The actual password
- Any reversible password data
**What IS stored:**
- Public verification key (a hash derived from the secret)
- Service description
- Password length
### Data Compatibility
- Uses the same `~/.config/smart_password_manager/passwords.json` format as the Python, JavaScript, Kotlin, Go and C# implementations
- Same algorithm, so metadata can be moved between platforms without conversion
- The Rust TUI (`smart-password-manager-tui`) and GUI (`smart-password-manager`) share the same file
---
## Security Model
- **Proof of knowledge**: Public keys verify secrets without exposing them
- **Decentralized trust**: No third party needed — you control your secrets completely
- **Deterministic security**: Same secret + same length = same password, always
- **Metadata separation**: Non-sensitive data stored separately from verification
- **Local processing**: No data leaves your computer
- **No recovery backdoors**: Lost secret phrase = permanently lost access, by design
### Decentralized Nature
**There is no "forgot password" button.** This is by design:
- No central server can reset your passwords
- No support team can recover your access
- Your secret phrase is the ONLY key
**This is the price of true decentralization** — you are completely in control.
---
## Security Warnings
### Secret Phrase Security
**Your secret phrase is the cryptographic master key**
1. **Permanent data loss**: Lost secret phrase = irreversible loss of all derived passwords
2. **No recovery mechanisms**: No password recovery, no secret reset, no administrative override
3. **Deterministic generation**: Identical input (secret + length) = identical output (password)
4. **Single point of failure**: Secret phrase is the sole authentication factor for all passwords
5. **Secure storage required**: Digital storage of secret phrases is prohibited
**Critical**: Test password regeneration with non-essential accounts before production use.
### Secret Phrase Requirements
- **Minimum 12 characters** (enforced by the application)
- Case-sensitive
- Use a mix of: uppercase, lowercase, numbers, symbols, emoji, or Cyrillic
- **Never store digitally**
- **NEVER use your password description as your secret phrase**
### Strong Secret Examples
```
✅ "MyStrongSecretPhrase2026!" — mixed case + numbers + symbols
✅ "P@ssw0rd!LongSecret" — special chars + numbers + length
✅ "КотБегемот2026НаДиете" — Cyrillic + numbers
✅ "Correct-Horse-Battery-42" — memorable phrase with separator
```
### Weak Secret Examples (avoid)
```
❌ "short" — too short, rejected
❌ "GitHub Account" — using description as secret (weak!)
❌ "password" — dictionary word, too short
❌ "1234567890" — only digits, too short
❌ "qwerty123" — keyboard pattern
❌ Same as description — never use the same value as description
```
### Password Length Requirements
- **Smart passwords**: 12–100 characters
---
## Technical Foundation
Powered by [**smartpasslib**](https://github.com/smartlegionlab/smartpasslib-rs) — the core library for deterministic password generation.
**Key derivation:**
| Private Key | 15–30 (dynamic) | Password generation (never stored, never transmitted) |
| Public Key | 45–60 (dynamic) | Verification (stored locally) |
**Character set (Google-compatible):**
```
!@#$%^&*()_+-=[]{};:,.<>?/ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyz
```
**Validation rules:**
- Secret phrase: minimum 12 characters
- Password length: 12–100 characters
---
## Cross-Platform Implementations
The same deterministic algorithm is available in multiple languages. Smart Password Manager CLI produces identical passwords to:
| Python | [smartpasslib](https://github.com/smartlegionlab/smartpasslib) |
| JavaScript | [smartpasslib-js](https://github.com/smartlegionlab/smartpasslib-js) |
| Kotlin | [smartpasslib-kotlin](https://github.com/smartlegionlab/smartpasslib-kotlin) |
| Go | [smartpasslib-go](https://github.com/smartlegionlab/smartpasslib-go) |
| C# | [smartpasslib-csharp](https://github.com/smartlegionlab/smartpasslib-csharp) |
| **Rust** | [smartpasslib-rs](https://github.com/smartlegionlab/smartpasslib-rs) |
**Data transfer:** Metadata can be moved between platforms through the shared `passwords.json` format.
---
## Research Paradigms & Publications
- **[Pointer-Based Security Paradigm](https://doi.org/10.5281/zenodo.17204738)** — Architectural Shift from Data Protection to Data Non-Existence
- **[Local Data Regeneration Paradigm](https://doi.org/10.5281/zenodo.17264327)** — Ontological Shift from Data Transmission to Synchronous State Discovery
---
## Build from Source
Requirements:
- Rust 1.88 or newer (edition 2024)
- Cargo
```bash
git clone https://github.com/smartlegionlab/smart-password-manager-cli-rs.git
cd smart-password-manager-cli-rs
cargo build --release
./target/release/smart-password-manager-cli --help
```
For development:
```bash
cargo run -- --help
```
---
## Ecosystem
**Core Libraries:**
- **[smartpasslib](https://github.com/smartlegionlab/smartpasslib)** — Python
- **[smartpasslib-js](https://github.com/smartlegionlab/smartpasslib-js)** — JavaScript
- **[smartpasslib-kotlin](https://github.com/smartlegionlab/smartpasslib-kotlin)** — Kotlin
- **[smartpasslib-go](https://github.com/smartlegionlab/smartpasslib-go)** — Go
- **[smartpasslib-csharp](https://github.com/smartlegionlab/smartpasslib-csharp)** — C#
- **[smartpasslib-rs](https://github.com/smartlegionlab/smartpasslib-rs)** — Rust
**CLI Applications:**
- **[CLI Smart Password Manager (Python)](https://github.com/smartlegionlab/clipassman)**
- **[CLI Smart Password Generator (Python)](https://github.com/smartlegionlab/clipassgen)**
- **[CLI Smart Password Manager (C#)](https://github.com/smartlegionlab/SmartPasswordManagerCsharpCli)**
- **[CLI Smart Password Generator (C#)](https://github.com/smartlegionlab/SmartPasswordGeneratorCsharpCli)**
- **CLI Smart Password Manager (Rust)** — this project
**Desktop Applications:**
- **[Desktop Smart Password Manager (Python)](https://github.com/smartlegionlab/smart-password-manager-desktop)**
- **[Desktop Smart Password Manager (C#)](https://github.com/smartlegionlab/SmartPasswordManagerCsharpDesktop)**
- **[Desktop Smart Password Manager (Rust, GUI)](https://github.com/smartlegionlab/smart-password-manager-gui-rs)**
- **[Desktop Smart Password Manager (Rust, TUI)](https://github.com/smartlegionlab/smart-password-manager-tui-rs)**
**Other:**
- **[Web Smart Password Manager](https://github.com/smartlegionlab/smart-password-manager-web)**
- **[Android Smart Password Manager](https://github.com/smartlegionlab/smart-password-manager-android)**
---
## Project Layout
```
smart-password-manager-cli-rs/
├── .github/
│ └── workflows/
│ ├── publish.yml
│ └── release.yml
├── src/
│ ├── main.rs Entry point
│ ├── cli.rs clap command definitions
│ ├── secret.rs Secret phrase input resolution
│ ├── output.rs stdout / stderr helpers
│ ├── clipboard.rs System clipboard + OSC 52
│ ├── qr.rs Terminal QR rendering
│ └── commands/
│ ├── mod.rs Entry lookup, confirmation
│ ├── add.rs
│ ├── get.rs
│ ├── list.rs
│ ├── delete.rs
│ ├── edit.rs
│ └── verify.rs
├── .gitignore
├── Cargo.toml
├── Cargo.lock
├── LICENSE
├── README.md
├── install.sh
└── uninstall.sh
```
---
## License
**[BSD 3-Clause License](LICENSE)**
Copyright (©) 2026, [Alexander Suvorov](https://github.com/smartlegionlab)
---
## Author
**Alexander Suvorov**
- GitHub: [smartlegionlab](https://github.com/smartlegionlab)
- Website: [smartlegionlab.github.io](https://smartlegionlab.github.io)
---
## Support
- **CLI Issues**: [GitHub Issues](https://github.com/smartlegionlab/smart-password-manager-cli-rs/issues)
- **Core Library Issues**: [smartpasslib Issues](https://github.com/smartlegionlab/smartpasslib/issues)
**Note**: Always test password regeneration with non-essential accounts first. Implementation security depends on proper usage.
---
## Links
- Repository: https://github.com/smartlegionlab/smart-password-manager-cli-rs
- Website: https://smartlegionlab.github.io
- Core library: https://github.com/smartlegionlab/smartpasslib-rs
---
## ⚠️ Disclaimer
**By using this software, you agree to the full disclaimer terms.**
**Summary:** Software provided "AS IS" without warranty. You assume all risks.
**Full legal disclaimer:** See [DISCLAIMER.md](https://github.com/smartlegionlab/smart-password-manager-cli-rs/blob/master/DISCLAIMER.md)