CLI API Reference¶

Complete API reference for UUID-Forge command-line interface.

Overview¶

The UUID-Forge CLI provides command-line access to all core functionality including UUID generation, configuration management, and security validation.

CLI Module Reference¶

uuid_forge.cli ¶

Command-line interface for UUID-Forge.

This module provides a comprehensive CLI for generating deterministic UUIDs, managing configuration, and validating security settings. The CLI is designed as a first-class interface to the library, suitable for both interactive use and automation in scripts and CI/CD pipelines.

Functions:

Name	Description
`generate`	Generate a deterministic UUID for an entity.
`extract`	Extract the UUID from a prefixed identifier.
`new_salt`	Generate a new cryptographic salt for UUID generation.
`init`	Initialize a new configuration file with generated salt.
`validate`	Validate current configuration for security best practices.
`info`	Display information about current configuration and usage.
`docs`	Build or serve the documentation locally.
`test`	Run the test suite with pytest.

Attributes:

Name	Type	Description
`app`

Attributes¶

app `module-attribute` ¶

app = Typer(
    name="uuid-forge",
    help="Deterministic UUID generation for cross-system coordination",
    add_completion=False,
)

Functions¶

generate ¶

generate(
    entity_type=Argument(
        ..., help="Type of entity (e.g., 'invoice', 'order', 'user')"
    ),
    prefix=Option(
        None, "--prefix", "-p", help="Human-readable prefix for the UUID"
    ),
    separator=Option(
        "-", "--separator", "-s", help="Separator between prefix and UUID"
    ),
    namespace=Option(
        None,
        "--namespace",
        "-n",
        help="Custom namespace domain (e.g., 'mycompany.com')",
    ),
    salt=Option(
        None, "--salt", help="Cryptographic salt (leave empty to use env var)"
    ),
    use_env=Option(
        True,
        "--env/--no-env",
        help="Load configuration from environment variables",
    ),
    attributes=Option(
        None,
        "--attr",
        "-a",
        help="Attributes in key=value format (can be used multiple times)",
    ),
)

Generate a deterministic UUID for an entity.

This command generates a UUID that will be identical for the same inputs and configuration. Perfect for coordinating IDs across multiple storage systems (Postgres, S3, Redis, etc.) without requiring inter-service communication.

Examples:

Simple generation with environment config¶

$ uuid-forge generate invoice --attr region=EUR --attr number=12345

With human-readable prefix¶

$ uuid-forge generate invoice --prefix INV-EUR --attr region=EUR --attr number=12345

Custom namespace and salt¶

$ uuid-forge generate user --namespace mycompany.com --salt "my-secret" --attr email=user@example.com

Using environment variables only¶

$ export UUID_FORGE_SALT="xvW9Kz_kRzPmNqYvTaWcXdYeFgZhAiB" $ export UUID_FORGE_NAMESPACE="mycompany.com" $ uuid-forge generate invoice --attr region=EUR --attr number=12345

extract ¶

extract(
    prefixed_id=Argument(..., help="Prefixed UUID to extract from"),
    separator=Option(
        "-", "--separator", "-s", help="Separator between prefix and UUID"
    ),
)

Extract the UUID from a prefixed identifier.

This command parses a prefixed UUID (created with --prefix option) and extracts just the UUID portion. Useful for database queries or API calls that require the pure UUID.

Examples:

Extract from prefixed UUID¶

$ uuid-forge extract "INV-EUR-550e8400-e29b-41d4-a716-446655440000"

With custom separator¶

$ uuid-forge extract "INV_EUR_550e8400-e29b-41d4-a716-446655440000" --separator "_"

new_salt ¶

new_salt(
    length=Option(
        32, "--length", "-l", help="Length of salt in bytes (minimum 16)"
    ),
)

Generate a new cryptographic salt for UUID generation.

This command creates a secure random salt that should be used in production environments. The salt should be generated once per deployment and stored securely in environment variables or secret management systems.

WARNING: Keep the salt secret! Anyone with the salt can predict your UUIDs.

Examples:

Generate standard 32-byte salt¶

$ uuid-forge new-salt

Generate longer salt for extra security¶

$ uuid-forge new-salt --length 64

init ¶

init(
    output=Option(
        Path(".env"),
        "--output",
        "-o",
        help="Output path for configuration file",
    ),
    force=Option(False, "--force", "-f", help="Overwrite existing file"),
)

Initialize a new configuration file with generated salt.

This command creates a template configuration file (.env format) with a freshly generated salt and usage instructions. Perfect for setting up new projects or deployments.

Examples:

Create .env in current directory¶

$ uuid-forge init

Create in custom location¶

$ uuid-forge init --output config/uuid.env

Overwrite existing file¶

$ uuid-forge init --force

validate ¶

validate(strict=Option(False, '--strict', help='Treat warnings as errors'))

Validate current configuration for security best practices.

This command checks your current configuration (loaded from environment variables) against security best practices. Use this in CI/CD pipelines to ensure production deployments have secure configurations.

Examples:

Validate current config¶

$ uuid-forge validate

Strict mode (warnings cause failure)¶

$ uuid-forge validate --strict

info ¶

info()

Display information about current configuration and usage.

This command shows the current configuration loaded from environment variables, system information, and usage examples. Useful for debugging configuration issues.

docs ¶

docs(
    serve=Option(
        True,
        "--serve/--build",
        help="Serve docs with live reload or just build",
    ),
    host=Option("127.0.0.1", "--host", "-h", help="Host to serve on"),
    port=Option(8000, "--port", "-p", help="Port to serve on"),
    open_browser=Option(
        True, "--open/--no-open", help="Open browser automatically"
    ),
)

Build or serve the documentation locally.

This command builds the MkDocs documentation and optionally serves it with live reload. Perfect for local development and documentation preview. No Docker required!

Examples:

Serve docs with live reload (default)¶

$ uuid-forge docs

Serve on different port¶

$ uuid-forge docs --port 8080

Build without serving¶

$ uuid-forge docs --build

Serve on all interfaces¶

$ uuid-forge docs --host 0.0.0.0 --port 8000

test ¶

test(
    coverage=Option(
        True, "--coverage/--no-coverage", help="Run with coverage reporting"
    ),
    verbose=Option(False, "--verbose", "-v", help="Verbose test output"),
    pattern=Option(
        None, "--pattern", "-k", help="Only run tests matching pattern"
    ),
    fail_fast=Option(
        False, "--fail-fast", "-x", help="Stop on first test failure"
    ),
    parallel=Option(False, "--parallel", "-n", help="Run tests in parallel"),
)

Run the test suite with pytest.

This command runs the project's test suite using pytest with various options for coverage, verbosity, and test selection. Perfect for local development and CI/CD pipelines.

Examples:

Run all tests with coverage (default)¶

$ uuid-forge test

Run tests without coverage¶

$ uuid-forge test --no-coverage

Run specific test pattern¶

$ uuid-forge test --pattern "test_core"

Verbose output and fail fast¶

$ uuid-forge test --verbose --fail-fast

Commands¶

generate¶

Generate a deterministic UUID for an entity.

Signature:

def generate(
    entity_type: str,
    prefix: str | None = None,
    separator: str = "-",
    namespace: str | None = None,
    salt: str | None = None,
    use_env: bool = True,
    attributes: list[str] | None = None,
) -> None

Arguments: - entity_type - Type of entity (e.g., 'invoice', 'order', 'user') [required]

Options: - --prefix, -p - Human-readable prefix for the UUID - --separator, -s - Separator between prefix and UUID (default: -) - --namespace, -n - Custom namespace domain - --salt - Cryptographic salt - --env/--no-env - Load configuration from environment variables (default: True) - --attr, -a - Attributes in key=value format (repeatable)

Example:

uuid-forge generate invoice --attr region=EUR --attr number=12345

extract¶

Extract the UUID portion from a prefixed identifier.

Signature:

def extract(
    prefixed_id: str
) -> None

Arguments: - prefixed_id - Prefixed identifier (e.g., "INV-EUR-550e8400-...") [required]

Example:

uuid-forge extract "INV-EUR-550e8400-e29b-41d4-a716-446655440000"

new-salt¶

Generate a new cryptographically secure salt.

Signature:

def new_salt() -> None

Example:

uuid-forge new-salt

init¶

Initialize a new configuration file with generated salt.

Signature:

def init(
    file: str | None = None,
    force: bool = False
) -> None

Options: - --file, -f - Configuration file path (default: .env) - --force - Overwrite existing file

Example:

uuid-forge init --file .env.production

validate¶

Validate current configuration for security best practices.

Signature:

def validate() -> None

Example:

uuid-forge validate

info¶

Display information about current configuration and usage.

Signature:

def info() -> None

Example:

uuid-forge info

docs¶

Build or serve the documentation locally.

Signature:

def docs(
    command: str = "serve"
) -> None

Arguments: - command - Either 'serve' or 'build' (default: serve)

Example:

uuid-forge docs serve
uuid-forge docs build

test¶

Run the test suite with pytest.

Signature:

def test(
    args: list[str] | None = None
) -> None

Arguments: - args - Additional pytest arguments (optional)

Example:

uuid-forge test
uuid-forge test --cov

Environment Variables¶

The CLI respects the following environment variables:

Variable	Type	Description
`UUID_FORGE_SALT`	str	Cryptographic salt for UUID generation
`UUID_FORGE_NAMESPACE`	str	Default namespace domain

Exit Codes¶

Code	Meaning
0	Success
1	Error (invalid input, missing configuration, etc.)
2	Validation failure

Integration with Python API¶

The CLI is built on top of the core Python API. All functionality available via CLI is also available programmatically:

from uuid_forge import UUIDGenerator, IDConfig, Namespace
from uuid_forge.core import generate_salt, generate_uuid_with_prefix
from uuid_forge.config import init_config_file, validate_config_security

# Generate salt (equivalent to: uuid-forge new-salt)
salt = generate_salt()

# Generate UUID (equivalent to: uuid-forge generate)
config = IDConfig(namespace=Namespace("myapp.com"), salt=salt)
generator = UUIDGenerator(config)
uuid = generator.generate("user", email="alice@example.com")

# With prefix (equivalent to: uuid-forge generate --prefix)
prefixed = generate_uuid_with_prefix(
    entity_type="invoice",
    prefix="INV-EUR",
    namespace=Namespace("myapp.com"),
    salt=salt,
    region="EUR",
    number=12345
)

CLI API Reference¶

Overview¶

CLI Module Reference¶

uuid_forge.cli ¶

Attributes¶

app module-attribute ¶

Functions¶

generate ¶

Simple generation with environment config¶

With human-readable prefix¶

Custom namespace and salt¶

Using environment variables only¶

extract ¶

Extract from prefixed UUID¶

With custom separator¶

new_salt ¶

Generate standard 32-byte salt¶

Generate longer salt for extra security¶

init ¶

Create .env in current directory¶

Create in custom location¶

Overwrite existing file¶

validate ¶

Validate current config¶

Strict mode (warnings cause failure)¶

info ¶

docs ¶

Serve docs with live reload (default)¶

Serve on different port¶

Build without serving¶

Serve on all interfaces¶

test ¶

Run all tests with coverage (default)¶

Run tests without coverage¶

Run specific test pattern¶

Verbose output and fail fast¶

Commands¶

generate¶

extract¶

new-salt¶

init¶

validate¶

info¶

docs¶

test¶

Environment Variables¶

Exit Codes¶

Integration with Python API¶

See Also¶

app `module-attribute` ¶