pwkit 0.1.0

# pwkit

A secure password toolkit with customizable options and template support.

English | [日本語](README_ja.md)

## Features

- 🔐 Generate secure random passwords
- 📝 Template-based password generation for environment files
- 📋 Automatic clipboard copying
- 🧾 QR code generation
- ⚙️ Highly customizable (length, symbols, numbers)
- 🔁 Batch generation support

## Installation

```bash
cargo install --path .
```

## Usage

### Basic Password Generation

Generate a single password (default: 20 characters with numbers):

```bash
pwkit
```

Generate with custom length:

```bash
pwkit --length 32
```

Generate with symbols:

```bash
pwkit --symbols --length 24
```

Generate multiple passwords:

```bash
pwkit --batch 5
```

### Template Mode (Environment File Generation)

The template mode is perfect for generating environment files with multiple passwords while ensuring that related credentials share the same password.

#### Template Syntax

Use placeholders in your template files:

```
{{PWGEN}}                    # Anonymous password (20 chars, default settings)
{{PWGEN:name}}               # Named password (reused for same name)
{{PWGEN:name:32}}            # Custom length (32 chars)
{{PWGEN:name:32:symbols}}    # With symbols
```

**Important**: Placeholders with the same name will use the same password!

#### Example Template

Create a template file `template.env`:

```bash
# Database Configuration
DB_PASSWORD={{PWGEN:db_password}}
DB_USERNAME=admin

# Application Settings
APP_SECRET={{PWGEN:app_secret:32:symbols}}
API_KEY={{PWGEN:api_key:64}}

# Multiple services using same password
SERVICE_A_PASSWORD={{PWGEN:shared_pass}}
SERVICE_B_PASSWORD={{PWGEN:shared_pass}}
SERVICE_C_PASSWORD={{PWGEN:shared_pass}}
```

Generate the environment file:

```bash
# Output to stdout
pwkit --template template.env

# Save to file
pwkit --template template.env --env-output .env
```

#### Real-World Example: Ansible Automation Platform

Template file `aap.env.template`:

```bash
# Database
postgresql_admin_password={{PWGEN:db_password}}

# AAP Gateway
gateway_admin_password={{PWGEN:admin_password}}
gateway_pg_password={{PWGEN:db_password}}

# AAP Controller
controller_admin_password={{PWGEN:admin_password}}
controller_pg_password={{PWGEN:db_password}}

# EDA Controller
eda_admin_password={{PWGEN:admin_password}}
eda_pg_password={{PWGEN:db_password}}
```

Generate:

```bash
pwkit --template aap.env.template --env-output aap.env
```

This ensures:
- All admin passwords are the same
- All database passwords are the same
- But admin and database passwords are different

### Additional Options

#### QR Code Generation

Generate a password and display it as a QR code:

```bash
pwkit --qrcode --length 16
```

#### Save to File

```bash
pwkit --batch 10 --output passwords.txt
```

#### Global Options for Template Mode

You can set default options that apply to all placeholders:

```bash
# All passwords will include symbols by default
pwkit --template template.env --symbols

# Custom default length
pwkit --template template.env --length 32
```

## CLI Options

```
Options:
  -l, --length <LENGTH>       Length of the generated password [default: 20]
  -n, --numbers               Include numbers in the password
  -s, --symbols               Include symbols in the password
  -q, --qrcode                Display password as QR code
  -b, --batch <BATCH>         Number of passwords to generate [default: 1]
  -o, --output <OUTPUT>       Output passwords to file
  -t, --template <FILE>       Generate from template file
  -e, --env-output <FILE>     Output file for template mode
  -h, --help                  Print help
  -V, --version               Print version
```

## Template Placeholder Options

| Syntax | Description | Example |
|--------|-------------|---------|
| `{{PWGEN}}` | Anonymous password, default settings | Each occurrence generates unique password |
| `{{PWGEN:name}}` | Named password | Same name = same password |
| `{{PWGEN:name:LENGTH}}` | Custom length | `{{PWGEN:api:64}}` |
| `{{PWGEN:name:LENGTH:symbols}}` | With symbols | `{{PWGEN:secure:32:symbols}}` |

### Option Keywords

- `symbols`, `symbol`, `s` - Include symbols
- `nosymbols`, `ns` - Exclude symbols
- `numbers`, `number`, `n` - Include numbers
- `nonumbers`, `nn` - Exclude numbers

## Examples

### Example 1: Simple Password

```bash
$ pwkit
rx2lmH5m7UEon4DTGmoa

✅ First password copied to clipboard!
```

### Example 2: Multiple Passwords with Symbols

```bash
$ pwkit -s -b 3 -l 16
]Fc_&8BtSikMg]}m
9O&F]nlg^{>PlY8#
xrDHJU9MNvlZ(&4)

✅ First password copied to clipboard!
```

### Example 3: Template Generation

```bash
$ pwkit --template myapp.env.template --env-output .env
📄 Reading template from: myapp.env.template
🔍 Found 7 password placeholder(s)
  ✨ Generated password for 'db_password': 20 chars
  ✨ Generated password for 'admin_password': 20 chars

✅ Environment file generated: .env
```

## Character Sets

- **Lowercase**: a-z
- **Uppercase**: A-Z
- **Numbers**: 0-9
- **Symbols**: `!@#$%^&*()-_=+[]{};:,.<>?`

## Security Notes

- Uses cryptographically secure random number generation via Rust's `rand` crate
- Passwords are generated locally and never sent over the network
- For production use, consider using a dedicated secrets management solution

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.