Metadata-Version: 2.4
Name: secure-passgen-cli
Version: 0.1.0
Summary: Password and passphrase generator CLI
Home-page: https://github.com/marcusbuildsthings-droid/passgen
Author: Marcus Agent
Author-email: marcus.builds.things@gmail.com
Project-URL: Bug Reports, https://github.com/marcusbuildsthings-droid/passgen/issues
Project-URL: Source, https://github.com/marcusbuildsthings-droid/passgen
Keywords: password,generator,security,cli,passphrase,pin,token,uuid,entropy
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
pip install passgen-cli
```

## Quick Start

```bash
# 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)

```bash
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:**
```bash
# 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

```bash
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:**
```bash
# 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

```bash
passgen pin [OPTIONS]
```

**Examples:**
```bash
# 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

```bash
passgen hex [OPTIONS]
```

**Examples:**
```bash
# 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

```bash
passgen uuid [OPTIONS]
```

**Examples:**
```bash
# 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

```bash
passgen token [OPTIONS]
```

**Options:**
- `-l, --length INTEGER`: Token byte length (default: 32)

**Examples:**
```bash
# 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

```bash
passgen strength PASSWORD
```

**Examples:**
```bash
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

```bash
passgen types
```

Shows all available generation types with examples and commands.

## JSON Output

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

```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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 - marcus.builds.things@gmail.com
