secure-passgen-cli 0.1.0

Password and passphrase generator CLI

passgen-cli

Password and passphrase generator CLI for developers, sysadmins, and security professionals.

Generate secure passwords, memorable passphrases, PINs, API tokens, UUIDs, and more from the command line. Perfect for automation, development workflows, and AI agent integration.

Features

🔐 Multiple Generation Types

• Passwords: Random character combinations with customizable rules
• Passphrases: Word-based phrases that are memorable yet secure
• PINs: Numeric codes for simple authentication
• Hex strings: For cryptographic keys and identifiers
• UUIDs: Universally unique identifiers
• Tokens: Base64 API tokens for authentication

🛡️ Security Features

• Uses Python's secrets module for cryptographically secure randomness
• Entropy calculation and strength assessment
• Customizable character sets and exclusions
• Safe symbol sets to avoid problematic characters

🤖 AI Agent Friendly

• JSON output on all commands (--json)
• Consistent CLI patterns and exit codes
• Comprehensive SKILL.md documentation
• Batch generation support

Installation

pip install passgen-cli

Quick Start

# Generate a default password (12 characters)
passgen

# Generate 5 passwords, 16 characters each
passgen -l 16 -n 5

# Generate a word-based passphrase
passgen passphrase

# Generate a 6-digit PIN
passgen pin -l 6

# Generate an API token
passgen token

# Check password strength
passgen strength "MyP@ssw0rd!"

Commands

Password Generation (Default)

passgen [OPTIONS]

Options:

• -l, --length INTEGER: Password length (default: 12)
• -n, --count INTEGER: Number of passwords (default: 1)
• --no-upper: Exclude uppercase letters
• --no-lower: Exclude lowercase letters
• --no-digits: Exclude digits
• --no-symbols: Exclude symbols
• --safe-symbols: Use only safe symbols (!@#$%^&*-_=+)
• --exclude-similar: Exclude similar chars (il1Lo0O)
• --custom-chars TEXT: Use custom character set
• --json: Output as JSON

Examples:

# Basic password
passgen
# → X8k$m2P9qL5w

# Long password without symbols
passgen -l 20 --no-symbols
# → A5m9K2n7P3x8Q4r6T1u0

# Safe symbols only (good for systems that don't like complex symbols)
passgen --safe-symbols
# → P@ssw0rd-123

# Custom character set
passgen --custom-chars "ABCDEF0123456789" -l 16
# → A1B2C3D4E5F6A1B2

Passphrase Generation

passgen passphrase [OPTIONS]

Options:

• -w, --words INTEGER: Number of words (default: 4)
• -s, --separator TEXT: Word separator (default: -)
• -c, --capitalize: Capitalize first letter of each word
• -n, --numbers: Add numbers at the end
• --number-digits INTEGER: Number of digits to add (default: 2)
• --count INTEGER: Number of passphrases
• --json: Output as JSON

Examples:

# Basic passphrase
passgen passphrase
# → apple-beach-chair-dance

# Capitalized with numbers
passgen passphrase -c -n
# → Apple-Beach-Chair-Dance-42

# Space-separated
passgen passphrase -s " " -w 5
# → apple beach chair dance eagle

# Multiple passphrases
passgen passphrase -n 3
# → knife-lemon-mouse-night
# → ocean-plant-quick-river
# → stone-table-under-voice

PIN Generation

passgen pin [OPTIONS]

Examples:

# 4-digit PIN
passgen pin
# → 7429

# 6-digit PIN
passgen pin -l 6
# → 185047

# Multiple PINs
passgen pin -n 5
# → 1234
# → 5678
# → 9012
# → 3456
# → 7890

Hex String Generation

passgen hex [OPTIONS]

Examples:

# 32-character hex string
passgen hex
# → a1b2c3d4e5f6789012345678901234ab

# Short hex for IDs
passgen hex -l 8
# → a1b2c3d4

# Multiple hex strings
passgen hex -l 16 -n 3
# → a1b2c3d4e5f67890
# → 1234567890abcdef
# → fedcba0987654321

UUID Generation

passgen uuid [OPTIONS]

Examples:

# Single UUID
passgen uuid
# → f47ac10b-58cc-4372-a567-0e02b2c3d479

# Multiple UUIDs
passgen uuid -n 3
# → 550e8400-e29b-41d4-a716-446655440000
# → 6ba7b810-9dad-11d1-80b4-00c04fd430c8
# → 6ba7b811-9dad-11d1-80b4-00c04fd430c8

Token Generation

passgen token [OPTIONS]

Options:

• -l, --length INTEGER: Token byte length (default: 32)

Examples:

# 32-byte base64 token
passgen token
# → mQz8kF3bX7vN2pL9wR1sA6tY4hJ5cE8uI0oP2qR3sT4u

# Shorter token (16 bytes)
passgen token -l 16
# → kF3bX7vN2pL9wR1s

# API key style (48 bytes)
passgen token -l 48
# → Very-long-base64-encoded-token-string-here

Strength Analysis

passgen strength PASSWORD

Examples:

passgen strength "password123"
# → Password: password123
# → Length: 11 characters
# → Entropy: 35.42 bits
# → Strength: Weak
# → Character variety: 2/4
# → 
# → Character types:
# →   Lowercase: ✓
# →   Uppercase: ✗
# →   Digits: ✓
# →   Symbols: ✗

passgen strength "MyP@ssw0rd!" --json
# → {
# →   "length": 11,
# →   "entropy_bits": 65.42,
# →   "strength": "Very Strong",
# →   "has_lowercase": true,
# →   "has_uppercase": true,
# →   "has_digits": true,
# →   "has_symbols": true,
# →   "charset_variety": 4
# → }

List Types

passgen types

Shows all available generation types with examples and commands.

JSON Output

All commands support --json flag for machine-readable output:

passgen -l 16 --json
# {
#   "type": "password",
#   "count": 1,
#   "length": 16,
#   "passwords": ["X8k$m2P9qL5w3R7z"],
#   "config": {
#     "include_upper": true,
#     "include_lower": true,
#     "include_digits": true,
#     "include_symbols": true,
#     "safe_symbols": false,
#     "exclude_similar": false,
#     "custom_chars": null
#   }
# }

passgen passphrase --json
# {
#   "type": "passphrase",
#   "count": 1,
#   "passphrases": ["apple-beach-chair-dance"],
#   "config": {
#     "words": 4,
#     "separator": "-",
#     "capitalize": false,
#     "add_numbers": false,
#     "number_digits": 2
#   }
# }

Security Considerations

• Cryptographically secure: Uses Python's secrets module, not random
• No predictable patterns: Each generation is independent and random
• Entropy calculation: Provides actual entropy measurements
• Character exclusions: Can exclude ambiguous characters (0/O, 1/l/I)
• Safe symbol sets: Option to use symbols that don't break shells/systems

Common Use Cases

Development:

# Database passwords
passgen -l 20 --safe-symbols

# API keys
passgen token -l 32

# User account passwords
passgen -l 12 -n 100 --json | jq -r '.passwords[]'

System Administration:

# Service account passwords
passgen passphrase -c -n -w 3

# PIN codes for MFA
passgen pin -l 6 -n 50

# Session IDs
passgen hex -l 32

Security Testing:

# Test password strength
passgen strength "$(passgen -l 8)"

# Generate test data
passgen uuid -n 1000 --json

Exit Codes

• 0: Success
• 1: Error (invalid arguments, generation failed)

For AI Agents, see SKILL.md

This tool is designed for AI agent automation. See SKILL.md for:

• Command reference with JSON schemas
• Common automation patterns
• Integration examples
• Error handling

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/marcusbuildsthings-droid/passgen

License

MIT License. See LICENSE file for details.

Author

Marcus Agent - [e-mail]