holecard-cli 0.4.1

A secure CLI password manager with dual-key encryption and TOTP support
holecard-cli-0.4.1 is not a library.

Crates.io License CI

A secure CLI password manager with dual-key encryption, TOTP support, and SSH key management.

Features

  • Dual-key encryption - Master password + secret key for enhanced security
  • Strong cryptography - Argon2id key derivation + AES-256-GCM encryption
  • System keyring integration - Secure storage with macOS/Linux keychain
  • TOTP support - Generate 2FA codes with auto-clipboard copy
  • SSH key management - Store and manage SSH keys with ssh-agent integration
  • Biometric authentication - Touch ID, Face ID, Apple Watch support on macOS
  • Session caching - Avoid repeated password prompts with configurable timeout

Quick Start

# Install from crates.io
cargo install holecard-cli

# Initialize deck
hc init

# Add a hand
hc hand add github -f username=myuser -f password=mypass

# Get a hand
hc hand get github

# Copy password to clipboard (auto-clears after 30s)
hc hand get github -c

Installation

From crates.io (Recommended)

cargo install holecard-cli

From source

git clone https://github.com/shabarba/holecard
cd holecard
cargo install --path .

From binary releases

Download pre-built binaries from GitHub Releases.

macOS (Apple Silicon):

curl -LO https://github.com/shabarba/holecard/releases/latest/download/hc-aarch64-apple-darwin.tar.gz
tar xzf hc-aarch64-apple-darwin.tar.gz
sudo mv hc /usr/local/bin/

Linux (x86_64):

curl -LO https://github.com/shabarba/holecard/releases/latest/download/hc-x86_64-unknown-linux-gnu.tar.gz
tar xzf hc-x86_64-unknown-linux-gnu.tar.gz
sudo mv hc /usr/local/bin/

With cargo-binstall

cargo binstall holecard-cli

Basic Usage

Managing Hands (Password Entries)

# Add hand with cards (key-value fields)
hc hand add aws -f access_key=AKIA... -f secret_key=...

# Add hand interactively
hc hand add

# List all hands
hc hand list

# Get hand details
hc hand get github

# Copy specific card to clipboard
hc hand get github -c password
hc hand get github -c username

# Edit hand
hc hand edit github -f password=newpass

# Remove hand
hc hand rm github

TOTP (Two-Factor Authentication)

# Add TOTP secret
hc totp add github JBSWY3DPEHPK3PXP

# Get TOTP code (displays + copies to clipboard)
hc totp get github
# Output: TOTP Code: 123456 (valid for 28 seconds)

# Remove TOTP secret
hc totp rm github

SSH Key Management

# Add SSH key from file
hc ssh add my-server \
  --private-key ~/.ssh/id_rsa \
  --username user \
  --hostname server.com \
  --passphrase "optional"

# Connect via SSH (auto-loads key)
hc ssh connect user@server.com
hc ssh connect my-server

# Pass additional SSH arguments
hc ssh connect prod -- -p 2222 -v

# List loaded keys
hc ssh list

# Unload key from ssh-agent
hc ssh unload my-server

Session Management

# Check session status
hc status

# Lock deck (clear cached session)
hc lock

# Configure session timeout (minutes)
hc config session-timeout 30

Advanced Features

URI-Based Secret Injection (1Password Compatible)

Inject secrets into config files using hc:// or op:// URI references:

# Create a template config file
cat > config.yaml << EOF
database:
  host: localhost
  username: hc://prod/db/username
  password: hc://prod/db/password
api:
  key: op://prod/api/secret_key
EOF

# Inject secrets (supports both hc:// and op:// URIs)
hc inject -i config.yaml -o config.prod.yaml

# Or from stdin
cat config.yaml | hc inject -i - > config.prod.yaml

URI Format: hc://[deck/]hand/card or op://[deck/]hand/card

Environment Variables with URIs

Run commands with secrets from URI references:

# Use hc:// or op:// URIs
hc run \
  --env DB_URL=hc://prod/db/connection_string \
  --env API_KEY=op://prod/api/key \
  -- python app.py

# Supports environment variable substitution
export DECK=production
hc run --env DB_PASS=hc://${DECK}/db/password -- ./deploy.sh

Import/Export

# Export deck to encrypted JSON
hc export backup.json

# Import from encrypted JSON
hc import backup.json
hc import backup.json --overwrite  # Replace existing hands

Biometric Authentication (macOS)

Touch ID, Face ID, and Apple Watch authentication:

# Enable/disable biometric auth (enabled by default on macOS)
hc config enable-biometric true

# After initial setup:
# - First unlock: Biometric + master password
# - Subsequent unlocks: Biometric only

Documentation

Security

Encryption

  • Key derivation: Argon2id (19MB memory, 2 iterations) with master password + secret key
  • Encryption: AES-256-GCM with random nonce per save
  • Secret key: 160-bit random key stored in system keyring

Session Caching

The derived encryption key is cached in the system keyring to avoid repeated password prompts. Sessions automatically expire after the configured timeout (default: 60 minutes).

Backup and Recovery

Use hc export to backup your deck:

hc export backup.json  # Encrypted with a password you choose

Important: Store export files securely. You need BOTH the export file and its password to restore your deck.

Building from Source

git clone https://github.com/shabarba/holecard
cd holecard

# Set up Git hooks (recommended for contributors)
cp .githooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push

# Build
cargo build --release

# Run tests
cargo test

# Lint
cargo clippy

# Format
cargo fmt

Git Hooks

The project includes a pre-push hook that automatically runs:

  • cargo fmt --check - Ensures code is properly formatted
  • cargo clippy -- -D warnings - Catches common mistakes and enforces best practices

This prevents CI failures by catching issues before pushing to remote.

Platform Support

  • macOS: Apple Silicon (aarch64) and Intel (x86_64)
  • Linux: x86_64 GNU

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

Licensed under either of:

at your option.

Acknowledgments

Built with: