idgen

A lightweight command-line utility for generating and inspecting various types of unique identifiers:

• UUID (versions 1, 3, 4, and 5)
• NanoID
• CUID (versions 1 and 2)
• ULID
• MongoDB ObjectID

This tool is designed for developers who need to generate or analyze various types of IDs during development, testing, debugging, or data migration.

Table of Contents

• idgen
  • Table of Contents
  • Features
  • Installation
    • From crates.io (Recommended)
    • Pre-built Binaries
    • Build from Source
  • Quick Start
  • Real-World Scenarios
    • Manual Database Inserts & Seeding
    • API Testing & Development
    • Scripting & Automation
    • Configuration & Secrets
    • Verification & Debugging
    • Distributed Tracing
    • Mock Data Generation
    • Cloud Resource Naming
    • Debugging & Inspection
  • ID Types and Use Cases
    • UUID (Universal Unique Identifier)
      • UUID v1 (Time-based)
      • UUID v4 (Random)
      • UUID v3/v5 (Name-based)
    • MongoDB ObjectID
    • NanoID
    • CUID (Collision-resistant Unique Identifier)
    • ULID (Universally Unique Lexicographically Sortable Identifier)
  • Usage Guide
    • Command Options
    • Format Options
    • Examples
    • Common UUID Namespaces
  • Why idgen?
  • Contributing
  • License

Features

• Generate UUIDs with support for all major versions (v1, v3, v4, v5)
• Create MongoDB-style ObjectIDs
• Generate URL-safe NanoIDs with configurable length
• Generate CUIDs (v1 and v2)
• Generate ULIDs
• Inspect and identify unknown IDs (detect type, version, and embedded timestamps)
• Multiple output formats (simple, hyphenated, URN)
• JSON output for scripting and automation
• Support for batch generation
• Custom prefix and suffix support
• Shell completions for bash, zsh, fish, and PowerShell
• Man page generation for Unix-like systems
• Banner-free mode by default (script-friendly)

Installation

From crates.io (Recommended)

cargo install idgen-cli

Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

# Linux/macOS: Make executable and move to PATH
chmod +x idgen-linux-amd64
sudo mv idgen-linux-amd64 /usr/local/bin/idgen

# Windows: Move to a directory in your PATH

Build from Source

1. Install Rust if not already installed
2. Build from source:

   git clone https://github.com/maniartech/idgen.git
   cd idgen
   cargo build --release
   

3. Copy binary to your PATH:

   # Linux/macOS
   cp target/release/idgen /usr/local/bin/
   
   # Windows (PowerShell, adjust path as needed)
   Copy-Item target/release/idgen.exe -Destination "$env:USERPROFILE/AppData/Local/Microsoft/WindowsApps/"
   

Quick Start

Generate a random UUID (v4):

idgen

Generate with banner:

idgen -b

Generate multiple IDs:

idgen -c 3

Real-World Scenarios

Manual Database Inserts & Seeding

Quickly generate IDs for manual SQL INSERT statements or when creating seed data files (CSV/JSON) for development databases.

# Generate 5 UUIDs for a seed file
idgen -c 5

API Testing & Development

Generate unique IDs on the fly when testing APIs with curl or Postman, especially for endpoints that require a unique request_id or transaction_id.

# Use in a curl request
curl -X POST https://api.example.com/users \
  -H "X-Request-ID: $(idgen -f simple)" \
  -d '{"name": "John"}'

Scripting & Automation

Use in CI/CD pipelines or shell scripts to generate unique filenames, deployment tags, or temporary resource identifiers.

# Create a unique temporary file
touch $(idgen -t nanoid -l 10 -p temp_ -s .log)

Configuration & Secrets

Generate unique strings for configuration files, such as JWT_SECRET, API_KEY, or session secrets during project setup.

# Generate a strong, random secret
idgen -t nanoid -l 64

Verification & Debugging

Verify the output of deterministic IDs (like UUID v5) to ensure your application logic matches the standard.

# Verify UUID v5 generation
idgen -t uuid5 --namespace URL --name "https://example.com"

Distributed Tracing

Generate a unique trace ID to manually tag a request flow across microservices when debugging.

# Generate a trace ID (UUID v4)
idgen -f simple

Mock Data Generation

Generate IDs for JSON mock files used in frontend development.

# Generate 10 NanoIDs for a mock user list
idgen -t nanoid -c 10

# Generate mock email addresses
idgen -t nanoid -l 8 -s @example.com -c 5

Cloud Resource Naming

Generate unique tags for cloud resources (AWS/Azure/GCP) during manual provisioning or Terraform/Ansible runs.

# Generate a unique suffix for an S3 bucket
idgen -t nanoid -l 8 -p my-bucket- | tr '[:upper:]' '[:lower:]'

Debugging & Inspection

Analyze unknown IDs found in logs or databases to determine their type, version, and creation timestamp (if available).

# Inspect an ID to see what it is
idgen inspect 01ARZ3NDEKTSV4RRFFQ69G5FAV

# Check if an ID is valid with JSON output
idgen inspect 550e8400-e29b-44d4-a716-446655440000 --json

ID Types and Use Cases

UUID (Universal Unique Identifier)

Standard 128-bit identifiers with multiple versions for different needs:

UUID v1 (Time-based)

• Format: Timestamp + node ID based
• Example: 550e8400-e29b-11d4-a716-446655440000
• Best for: Logging, temporal ordering, distributed systems

UUID v4 (Random)

• Format: Random numbers
• Example: 550e8400-e29b-44d4-a716-446655440000
• Best for: Default choice, database keys, session IDs

UUID v3/v5 (Name-based)

• v3 uses MD5, v5 uses SHA-1 (preferred)
• Example: cfbff0d1-9375-5685-968c-48ce8b15ae17
• Best for: Consistent IDs from same input, content addressing

MongoDB ObjectID

12-byte identifier combining timestamp, machine ID, and counter:

• Example: 507f1f77bcf86cd799439011
• Best for: Document IDs, chronological sorting

NanoID

Compact, URL-safe identifiers:

• Example: V1StGXR8_Z5jdHi6B-myT
• Best for: Short URLs, user-facing IDs, frontend generation

CUID (Collision-resistant Unique Identifier)

Designed for horizontal scaling and performance:

• v1: Original version
• v2: Secure, collision-resistant, optimized for modern web
• Best for: High-performance distributed systems

ULID (Universally Unique Lexicographically Sortable Identifier)

Sortable, random, 128-bit identifier:

• Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
• Best for: Database keys where sorting is important

Usage Guide

Command Options

Generate and inspect unique identifiers

Usage: idgen.exe [OPTIONS] [COMMAND]

Commands:
  inspect      Inspect an ID to determine its type and extract metadata
  completions  Generate shell completions
  help         Print this message or the help of the given subcommand(s)

Options:
  -t, --type <ID_TYPE>         Type of ID to generate [default: uuid4] [possible values: uuid1, uuid3, uuid4, uuid5, nanoid, cuid1, cuid2, ulid, objectid]
  -f, --format <FORMAT>        Output format for UUIDs [default: hyphenated] [possible values: hyphenated, simple, urn]
  -c, --count <COUNT>          Number of IDs to generate [default: 1]
  -l, --length <LENGTH>        Length for NanoID (default: 21)
  -p, --prefix <PREFIX>        Prefix to add to generated IDs [default: ]
  -s, --suffix <SUFFIX>        Suffix to add to generated IDs [default: ]
      --namespace <NAMESPACE>  Namespace UUID for v3/v5 (use DNS, URL, OID, X500, or a custom UUID)
      --name <NAME>            Name string for UUID v3/v5
      --json                   Output as JSON
  -b, --banner                 Show banner
  -h, --help                   Print help (see more with '--help')
  -V, --version                Print version

EXAMPLES:
    idgen                                       Generate a random UUID v4 (default)
    idgen -t uuid1                              Generate a time-based UUID v1
    idgen -t uuid3 --namespace DNS --name example.com
    idgen -t nanoid -l 10                       Generate a NanoID of length 10
    idgen -t ulid                               Generate a ULID
    idgen -c 5                                  Generate 5 UUIDs
    idgen -p 'test-' -s '.log'                  Add prefix and suffix
    idgen --json                                Output as JSON
    idgen inspect 550e8400-e29b-44d4-a716-446655440000
    idgen completions bash                      Generate bash completions

Format Options

Each ID can be formatted in different ways:

• Simple: No separators (550e8400e29b44d4a716446655440000)
• Hyphenated: Standard format (550e8400-e29b-44d4-a716-446655440000)
• URN: URN format (urn:uuid:550e8400-e29b-44d4-a716-446655440000)

Examples

# Generate IDs (default: UUID v4)
idgen                              # Random UUID v4
idgen -t uuid1                     # Time-based UUID v1
idgen -t uuid5 --namespace DNS --name example.com  # Name-based UUID v5

# ID Types
idgen -t nanoid                    # NanoID (21 chars)
idgen -t nanoid -l 10              # NanoID with custom length
idgen -t cuid1                     # CUID v1
idgen -t cuid2                     # CUID v2
idgen -t ulid                      # ULID
idgen -t objectid                  # MongoDB ObjectID

# UUID Formats
idgen -f simple                    # No hyphens: 550e8400e29b44d4a716446655440000
idgen -f urn                       # URN format: urn:uuid:550e8400-e29b-...

# Multiple IDs
idgen -c 5                         # Generate 5 UUIDs
idgen -t ulid -c 3                 # Generate 3 ULIDs

# Prefix and Suffix
idgen -p 'test-'                   # Add prefix
idgen -s '.log'                    # Add suffix
idgen -p 'user_' -s '_v1' -c 3     # Both prefix and suffix

# JSON Output
idgen --json                       # Single ID as JSON
idgen --json -c 3                  # Multiple IDs as JSON array

# Inspect IDs
idgen inspect 550e8400-e29b-44d4-a716-446655440000
idgen inspect 01ARZ3NDEKTSV4RRFFQ69G5FAV

# Shell Completions
idgen completions bash > ~/.bash_completion.d/idgen
idgen completions zsh > ~/.zsh/completions/_idgen
idgen completions fish > ~/.config/fish/completions/idgen.fish
idgen completions powershell >> $PROFILE

# Man Page
idgen manpage > /usr/local/share/man/man1/idgen.1

Common UUID Namespaces

For UUID v3/v5, use these standard namespaces:

• DNS: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
• URL: 6ba7b811-9dad-11d1-80b4-00c04fd430c8
• OID: 6ba7b812-9dad-11d1-80b4-00c04fd430c8
• X500: 6ba7b814-9dad-11d1-80b4-00c04fd430c8

Why idgen?

Key advantages:

• All-in-one: Single tool for 9 ID types instead of multiple utilities
• ID Inspector: Unique feature to analyze and identify unknown IDs
• Fast: Native Rust binary with no interpreter overhead
• Portable: No Node.js, Python, or other runtime required

Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, open an issue first.

License

MIT License - Copyright © 2021-2025 ManiarTech®