Quick Start

1. Download Aphelion

Download the CLI for your operating system:

Linux

macOS

Windows

2. Install Your License (Pro/Enterprise)

If you purchased a Pro or Enterprise license:

# Place the license file in your project root
mv ~/Downloads/.aphelion-license ./

# Or in your home directory
mkdir -p ~/.aphelion
mv ~/Downloads/.aphelion-license ~/.aphelion/

# Verify installation
aphelion license verify

3. Generate Your First Dataset

# Clone an existing database structure
aphelion clone postgres://user:pass@localhost:5432/prod_db \
  --output ./test_db.json \
  --rows 1000

# Generate synthetic data
aphelion generate ./test_db.json \
  --target postgres://user:pass@localhost:5432/test_db

Complete Workflow Examples

Basic Workflow

# Step 1: Clone production schema (read-only, safe)
aphelion clone postgres://readonly:pass@prod.example.com:5432/myapp \
  --output myapp-schema.json \
  --rows 10000 \
  --exclude audit_logs,sessions

# Step 2: Generate test data
aphelion generate myapp-schema.json \
  --target postgres://testuser:testpass@localhost:5432/myapp_test \
  --truncate

Using Environment Variables

Keep sensitive credentials out of command history:

# Set environment variables
export DB_USER="myuser"
export DB_PASS="mypassword"
export DB_HOST="localhost"
export DB_NAME="mydb"

# Use them in connection strings
aphelion clone "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:5432/${DB_NAME}" \
  --output schema.json

aphelion generate schema.json \
  --target "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:5432/test_${DB_NAME}"

⚠️ Handling Special Characters in Passwords

If your password contains special characters like $, @, #, &, etc., you must URL-encode them or use quotes properly: 

# Method 1: URL-encode special characters
# $ becomes %24, @ becomes %40, # becomes %23
export DB_PASS="my%24pass%40word"  # For password: my$pass@word

# Method 2: Use single quotes to prevent shell expansion
export DB_PASS='my$pass@word'  # Single quotes preserve literal values

# Method 3: Escape special characters
export DB_PASS="my\$pass@word"  # Backslash escapes the $

# Then use in connection string (always use double quotes)
aphelion clone "postgres://user:${DB_PASS}@localhost:5432/db" \
  --output schema.json

Common URL encodings: @ → %40, : → %3A, / → %2F, ? → %3F, # → %23, $ → %24

Reproducible Data (Same Seed)

Generate identical data every time for consistent testing:

# Generate with seed 42
aphelion generate schema.json \
  --target postgres://user:pass@localhost:5432/test_db \
  --seed 42

# Running again with same seed produces identical data
aphelion generate schema.json \
  --target postgres://user:pass@localhost:5432/test_db2 \
  --seed 42

CI/CD Integration (Pro/Enterprise)

Automated test data refresh in your pipeline:

#!/bin/bash
# .github/workflows/test-data.sh

# Use pipeline ID as seed for reproducibility
aphelion generate schema.json \
  --target $TEST_DB_URL \
  --seed $CI_PIPELINE_ID \
  --auto-approve \
  --truncate

# Run your tests
npm test

Controlling Data Volume

Three ways to control how much data is generated:

1. During Clone (Set Defaults)

aphelion clone postgres://... \
  --output schema.json \
  --rows 5000  # Each table gets 5,000 rows by default

2. During Generate (Override)

aphelion generate schema.json \
  --target postgres://... \
  --rows 50000  # Override to 50,000 rows per table

3. Edit Schema JSON (Per-Table Control)

{
  "tables": {
    "users": {
      "rowCount": 10000,    // 10k users
      ...
    },
    "orders": {
      "rowCount": 100000,   // 100k orders
      ...
    }
  }
}

Industry-Specific Templates

Aphelion includes pre-built, production-ready schemas for various industries. Use these as starting points or for testing:

Healthcare (HIPAA)

Complete EHR system with patients, encounters, medications, lab results, and clinical notes

aphelion generate examples/healthcare/schema.json \
  --target postgres://user:pass@localhost:5432/healthcare_test \
  --rows 5000

Tables: patients, encounters, medications, lab_results, diagnoses, procedures, clinical_notes

Investment Banking

Trading platform with securities, portfolios, trades, and market data 

aphelion generate examples/investment-banking/schema.json \
  --target postgres://user:pass@localhost:5432/trading_test \
  --rows 10000

Tables: securities, portfolios, trades, positions, market_data, clients

Retail Banking

Banking system with accounts, transactions, loans, and customers

aphelion generate examples/retail-banking/schema.json \
  --target postgres://user:pass@localhost:5432/banking_test \
  --rows 8000

Tables: customers, accounts, transactions, loans, cards, branches

Insurance

Insurance platform with policies, claims, and underwriting

aphelion generate examples/insurance/schema.json \
  --target postgres://user:pass@localhost:5432/insurance_test \
  --rows 5000

Tables: policies, claims, policyholders, coverage, premiums

E-commerce

Online store with products, orders, customers, and inventory

aphelion generate examples/ecommerce/schema.json \
  --target postgres://user:pass@localhost:5432/ecommerce_test \
  --rows 10000

Tables: products, orders, customers, inventory, reviews, categories

Airlines

Flight booking system with flights, bookings, and passengers

aphelion generate examples/airlines/schema.json \
  --target postgres://user:pass@localhost:5432/airlines_test \
  --rows 7000

Tables: flights, bookings, passengers, airports, aircraft

Template Features

  • ✅ Production-ready schemas - Based on real-world applications
  • ✅ Realistic data - Industry-specific PII detection and generation
  • ✅ Complex relationships - Foreign keys, constraints, and circular dependencies
  • ✅ Compliance-aware - HIPAA, PCI-DSS, GDPR considerations built-in

Core Features

Constraint-Safe Generation

Automatically respects all foreign keys, unique constraints, and NOT NULL requirements

PII Detection & Masking

Automatically detects and generates realistic fake data for emails, names, SSNs, credit cards, and more

Deterministic Output

Same seed = same data every time. Perfect for reproducible testing

Industry Templates

Pre-built schemas for Healthcare, Finance, E-commerce, and more

CLI Commands

aphelion clone

Extract schema from an existing database and save it as JSON

Basic Usage:

aphelion clone <connection-string> --output schema.json

Options:

  • --output, -o - Output file path (required)
  • --rows, -r - Default row count for generation (default: 100)
  • --tables, -t - Specific tables to clone (comma-separated)
  • --exclude - Tables to exclude (comma-separated)

Examples:

# Clone entire database
aphelion clone postgres://user:pass@localhost:5432/mydb \\
  --output schema.json

# Clone specific tables only
aphelion clone postgres://user:pass@localhost:5432/mydb \\
  --output schema.json \\
  --tables users,orders,products

# Clone with custom row count
aphelion clone postgres://user:pass@localhost:5432/mydb \\
  --output schema.json \\
  --rows 5000

aphelion generate

Generate synthetic data from a schema file

Basic Usage:

aphelion generate <schema-file> --target <connection-string>

Options:

  • --target, -t - Target database connection string (required)
  • --seed, -s - Random seed for deterministic output (default: random)
  • --rows, -r - Override row count from schema
  • --auto-approve - Skip confirmation prompts (Pro/Enterprise only)
  • --drop-existing - Drop existing tables before generation
  • --truncate - Truncate existing tables before generation

Examples:

# Basic generation
aphelion generate schema.json \\
  --target postgres://user:pass@localhost:5432/test_db

# Deterministic generation with seed
aphelion generate schema.json \\
  --target postgres://user:pass@localhost:5432/test_db \\
  --seed 12345

# CI/CD mode (Pro/Enterprise)
aphelion generate schema.json \\
  --target postgres://user:pass@localhost:5432/test_db \\
  --auto-approve \\
  --truncate

# Override row count
aphelion generate schema.json \\
  --target postgres://user:pass@localhost:5432/test_db \\
  --rows 10000

aphelion license

Manage and verify your Aphelion license

Subcommands:

# Verify license is valid
aphelion license verify

# Show license details
aphelion license info

# Show version
aphelion --version

License Locations:

Aphelion searches for licenses in this order:

  1. Current directory: ./.aphelion-license
  2. Home directory: ~/.aphelion/.aphelion-license

Getting Help

# Show all commands
aphelion --help

# Show command-specific help
aphelion clone --help
aphelion generate --help

Tier Comparison

Feature Free Pro Enterprise
Max Rows per Table 1,000 Unlimited Unlimited
CI/CD Auto-Approve ❌ ✅ ✅
Advanced PII Profiles ❌ ✅ ✅
Support Community Email Priority

Need Help?

Our team is here to support you

Contact Support