smart-password-manager-cli 0.1.0

Command line interface for smart password management built on smartpasslib. Generate deterministic passwords from secret phrases without storing them.
smart-password-manager-cli-0.1.0 is not a library.

Smart Password Manager CLI (Rust)

Command line interface for smart password management built on smartpasslib. 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 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.

Crates.io Documentation GitHub top language GitHub license GitHub release GitHub stars GitHub forks Platform Crates.io Downloads

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:

cargo install smart-password-manager-cli

Then run:

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

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)

curl -fsSL https://raw.githubusercontent.com/smartlegionlab/smart-password-manager-cli-rs/master/install.sh | bash

Installs the binary to ~/.local/bin/.

Uninstall

curl -fsSL https://raw.githubusercontent.com/smartlegionlab/smart-password-manager-cli-rs/master/uninstall.sh | bash

Your password metadata in ~/.config/smart_password_manager/passwords.json is never touched. Delete it manually if you want to remove it:

rm -rf ~/.config/smart_password_manager

Quick Usage Guide

Add an entry

smart-password-manager-cli add --description "GitHub Account" --length 24

Prompts for the secret phrase interactively. Alternatively:

# 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)
echo -n 'MyStrongSecretPhrase2026!' | \
  smart-password-manager-cli add --description "GitHub Account" --length 24 --secret-stdin

Get a password

# stdout
smart-password-manager-cli get --description "GitHub Account"

# pipe to system clipboard
smart-password-manager-cli get --description "GitHub Account" | xclip -selection clipboard
smart-password-manager-cli get --description "GitHub Account" | wl-copy
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

smart-password-manager-cli list
smart-password-manager-cli list --json

Edit metadata

smart-password-manager-cli edit --description "GitHub Account" --new-description "GitHub Personal" --new-length 32

Delete an entry

smart-password-manager-cli delete --description "GitHub Account"
smart-password-manager-cli delete --description "GitHub Account" --yes

Verify a secret

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

get (--key <KEY> | --description <TEXT>)
    [--secret <TEXT> | --secret-stdin]
    [--copy] [--qr] [--json]

list

list [--json]

delete

delete (--key <KEY> | --description <TEXT>) [--yes]

edit

edit (--key <KEY> | --description <TEXT>)
    [--new-description <TEXT>] [--new-length <N>]

verify

verify (--key <KEY> | --description <TEXT>) [--secret <TEXT> | --secret-stdin]

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:

smart-password-manager-cli get --description "GitHub Account" | xclip -selection clipboard
smart-password-manager-cli get --description "GitHub Account" | wl-copy
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:

Platform Path
Linux ~/.config/smart_password_manager/passwords.json
macOS ~/.config/smart_password_manager/passwords.json
Windows %USERPROFILE%\.config\smart_password_manager\passwords.json

Format:

{
  "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 — the core library for deterministic password generation.

Key derivation:

Key Type Iterations Purpose
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:

Language Repository
Python smartpasslib
JavaScript smartpasslib-js
Kotlin smartpasslib-kotlin
Go smartpasslib-go
C# smartpasslib-csharp
Rust smartpasslib-rs

Data transfer: Metadata can be moved between platforms through the shared passwords.json format.

Research Paradigms & Publications

Build from Source

Requirements:

  • Rust 1.88 or newer (edition 2024)
  • Cargo
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:

cargo run -- --help

Ecosystem

Core Libraries:

CLI Applications:

Desktop Applications:

Other:

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

Copyright (©) 2026, Alexander Suvorov

Author

Alexander Suvorov

Support

Note: Always test password regeneration with non-essential accounts first. Implementation security depends on proper usage.

Links

⚠️ 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