promocrypt-cli-1.1.1 is not a library.
promocrypt
_
_ __ _ __ ___ _ __ ___ ___ ___ _ __ _ _ _ __ | |_
| '_ \| '__/ _ \| '_ ` _ \ / _ \ / __| '__| | | | '_ \| __|
| |_) | | | (_) | | | | | | (_) | (__| | | |_| | |_) | |_
| .__/|_| \___/|_| |_| |_|\___/ \___|_| \__, | .__/ \__|
|_| |___/|_|
Command-line tool for cryptographically secure promotional code generation and management.
Generate millions of unique, validated promotional codes with machine-binding security, database integration, and flexible output formats.
Table of Contents
- Overview
- Features
- Installation
- Quick Start
- Commands Reference
- Database Integration
- Typed Column Values
- External Commands
- Code Formatting
- Check Position
- Storage Encryption
- History & Generation Log
- Secret Rotation
- Shell Completions
- Environment Variables
- Exit Codes
- Examples
- Building from Source
- License
Overview
promocrypt is a high-performance CLI for generating and managing promotional codes. Built on the promocrypt-core cryptographic library, it provides:
- Cryptographic security: Codes are generated using secure algorithms with embedded check digits
- Machine binding:
.binfiles can be locked to specific machines - Database integration: Direct insertion to PostgreSQL and SQLite
- Flexible formatting: Prefixes, suffixes, and separators (e.g.,
PROMO-XXXX-XXXX-2024) - Audit trail: Track generation history, secret rotations, and configuration changes
Features
| Feature | Description |
|---|---|
| Code Generation | Generate single codes or millions in batches |
| Code Validation | Validate codes from CLI, files, or databases |
| Database Insert | PostgreSQL and SQLite with batch insertion |
| Storage Encryption | Encrypt codes at rest (AES-256-SIV) |
| External Commands | Pipe to any script (Python, Node.js, etc.) |
| Output Formats | Plain text, JSON, CSV |
| Shell Completions | Bash, Zsh, Fish, PowerShell |
| Check Position | Configurable check digit placement |
| Code Formatting | Prefix, suffix, separators |
| Secret Rotation | Safely change passwords |
| History Tracking | Audit rotations, masterings, changes |
| Generation Log | Track when/how many codes generated |
| PG Sync | Import/export .bin to PostgreSQL |
| Dry-run Mode | Preview without generating |
| Rate Limiting | Control generation speed |
Installation
Download from Releases
Download the latest release for your platform:
# Linux (x86_64)
# macOS (Apple Silicon)
Build from Source
# Clone the repository
# Build release binary
# Install to PATH
Quick Start
1. Create a .bin file
# Create a new .bin file with default settings
# Create with custom formatting
2. Generate codes
# Generate a single code
# Generate 1000 codes to file
# Generate with database insertion
3. Validate codes
# Validate a single code
# Validate from file
# Validate with quiet mode (only show invalid)
Commands Reference
Global Options
promocrypt [OPTIONS] <COMMAND>
Options:
--bin <PATH> Path to .bin file (default: ./promocrypt.bin)
--format <FORMAT> Output format: plain, json, csv (default: plain)
--quiet Suppress non-essential output
--env-file <PATH> Load environment from file
-h, --help Print help
-V, --version Print version
create
Create a new .bin file.
)
)
)
)
)
)
)
# Basic
# With formatting
# With storage encryption
info
Show .bin file information.
)
generate
Generate promotional codes.
)
)
)
)
# Format options (override .bin config)
# Database options
)
)
# Typed column values
# External command
)
# Generate to stdout
# Generate to file
# Generate with database
# Dry run
validate
Validate promotional codes.
)
)
)
lookup
Look up code status in database.
<CODE> Code
)
)
)
stats
Show statistics about .bin file and database.
export
Export codes from database.
)
)
)
)
)
master
Master .bin for a different machine.
)
# Get your machine ID
# Master for another machine
config
View or modify .bin configuration.
)
)
)
rotate-secret
Rotate secret password.
)
history
View, export, or clear history.
)
generation-log
View, export, or clear generation log.
)
pg-import
Import .bin file into PostgreSQL.
)
)
)
pg-export
Export .bin from PostgreSQL to file.
)
)
)
)
completions
Generate shell completions.
<SHELL> Shell:
Database Integration
PostgreSQL Setup
- Create a database config file:
# db-postgres.toml
[]
= "postgresql"
= "localhost"
= 5432
= "mydb"
= "user"
= "password"
# OR use connection string:
# connection_string = "postgres://user:pass@localhost/mydb"
[]
= "promo_codes"
= "code"
[]
= 123
= "active"
- Create the table:
(
id SERIAL PRIMARY KEY,
code VARCHAR(50) UNIQUE NOT NULL,
campaign_id INTEGER,
status VARCHAR(20) DEFAULT 'active',
used_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW
);
- Generate codes:
SQLite Setup
- Create a database config file:
# db-sqlite.toml
[]
= "sqlite"
= "./codes.db"
[]
= "promo_codes"
= "code"
- Create the database:
- Generate codes:
Typed Column Values
Set column values with proper types during generation:
| Option | Type | Example |
|---|---|---|
--set |
String | --set status=active |
--set-int |
Integer | --set-int campaign_id=123 |
--set-float |
Float | --set-float discount=19.99 |
--set-bool |
Boolean | --set-bool single_use=true |
--set-now |
Timestamp | --set-now created_at |
--set-json |
JSON/JSONB | --set-json meta='{"source":"cli"}' |
--set-null |
NULL | --set-null deleted_at |
Priority: --set-* > --extra > config file
Example:
External Commands
Pipe codes to any external program for custom database insertion:
# Plain text (one code per line)
# JSON lines with extra data
Example Scripts
Bash + psql (PostgreSQL):
#!/bin/bash
while ; do
done
Python + MongoDB:
#!/usr/bin/env python3
=
=
=
Node.js + MySQL:
#!/usr/bin/env node
const mysql = require;
const readline = require;
;
Code Formatting
Prefix and Suffix
# Set during creation (stored in .bin)
# Override during generation
# Output: PROMO-A3KF7NP2XM-2024
Separators
# Create with separators at positions 4 and 8
# Output: XXXX-XXXX-XX
Check Position
The check digit position can be configured for security:
| Value | Meaning | Example (10-char) |
|---|---|---|
-1 |
End (default) | XXXXXXXXX[C] |
0 |
Start | [C]XXXXXXXXX |
4 |
Position 4 | XXXX[C]XXXXX |
-3 |
3rd from end | XXXXXXX[C]XX |
Security benefit: Attackers don't know where the check digit is located.
Storage Encryption
Enable storage encryption for codes stored in SQLite (desktop apps):
# Enable during creation
# Toggle on existing .bin
Algorithm: AES-256-SIV (deterministic, allows lookups)
History & Generation Log
View History
# View all history
# Export to JSON
# Clear (keep last 10)
View Generation Log
# View log
# View summary
# Export to JSON
Secret Rotation
Safely rotate the secret password:
After rotation:
- All future operations require the new secret
- The change is logged in history
Shell Completions
Bash
# Or system-wide:
Zsh
# Add to .zshrc:
fpath=(/.zsh/completions )
&&
Fish
PowerShell
promocrypt completions powershell >> $PROFILE
Environment Variables
| Variable | Description |
|---|---|
PROMOCRYPT_SECRET |
Default secret password |
PROMOCRYPT_BIN |
Default .bin file path |
DATABASE_URL |
Database connection string |
Example:
# No need to specify --secret or --bin
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Validation failed (some codes invalid) |
| 2 | File/path error |
| 3 | Authentication error (wrong secret/machine) |
| 4 | Database error |
| 5 | Configuration error |
| 6 | External command error |
| 7 | Code not found (lookup) |
Examples
Campaign Launch
# Create a campaign-specific .bin
# Generate 100,000 codes to database
Multi-Machine Deployment
# On development machine
# Output: a1b2c3d4e5f6...
# Get production server's machine ID
# Output: f6e5d4c3b2a1...
# Master the .bin for production
# Copy to production
Bulk Validation
# Validate codes from file
# Validate all codes in database
Export Unused Codes
# Export unused codes to CSV
# Export as SQL for migration
Building from Source
Requirements
- Rust 1.89.0+
- OpenSSL development libraries (Linux)
Build
# Debug build
# Release build
# Run tests
Cross-compilation
# For Linux from macOS
License
MIT License - see LICENSE for details.
Made with Rust