# mkid

A tiny Rust-based CLI tool to generate unique IDs, primarily UUIDs. Built as a more capable alternative to `uuidgen`, with support for all UUID versions (v1-v8), multiple output formats, and clipboard integration.

## Features

- **Quick shortcuts**: `mkid4` and `mkid7` for instant UUID generation
- **All UUID versions supported**: v1 through v8
- **Smart defaults**: `mkid` generates UUID v7 (sortable, database-friendly)
- **Multiple formats**: hyphenated, simple, URN, braced
- **Case control**: lowercase (default) or uppercase
- **Clipboard integration**: Copy output directly to clipboard
- **Bulk generation**: Generate multiple UUIDs at once
- **Fast and lightweight**: Three small binaries, minimal dependencies

## Installation

### With cargo-binstall (recommended)

The fastest way to install pre-built binaries:

```bash
cargo binstall mkid
```

### From GitHub releases

Download pre-built binaries directly from [GitHub releases](https://github.com/asaaki/mkid/releases).

### From crates.io

Build from source via crates.io:

```bash
cargo install mkid --locked
```

### From source

Build from the repository:

```bash
git clone https://github.com/asaaki/mkid
cd mkid
cargo install --path .
```

## Usage

### Quick Shortcuts

For maximum convenience, use the shortcut commands:

```bash
# UUID v4 (random) - fastest way
mkid4
# Output: 18431fda-68f1-42af-9318-1ece3d60281e

# UUID v7 (sortable) - fastest way
mkid7
# Output: 019c1064-a92c-74f0-98d9-03496f8a9693
```

### Basic Usage

Generate a UUID v7 (default):
```bash
mkid
# Output: 019c0edc-d74c-7c02-beb9-40fcf2eee5f6
```

### UUID Versions

Generate specific UUID versions:

```bash
# UUID v4 (random)
mkid uuid v4

# UUID v7 (timestamp-based, sortable)
mkid uuid v7

# UUID v1 (time-based with node ID)
mkid uuid v1 --random-node

# UUID v3 (MD5 hash-based)
mkid uuid v3 --namespace dns --name example.com

# UUID v5 (SHA-1 hash-based)
mkid uuid v5 --namespace url --name https://example.com

# UUID v6 (sortable time-based)
mkid uuid v6 --random-node

# UUID v8 (custom)
mkid uuid v8 --bytes 0123456789abcdef0123456789abcdef
```

### Version-Specific Options

**For v1/v6 (time-based):**
- `--random-node`: Use random 6-byte node ID (default)
- `--node-id <HEX>`: Specify custom node ID (12 hex characters)

```bash
mkid uuid v1 --node-id aabbccddeeff
```

**For v3/v5 (hash-based):**
- `--namespace <NS>`: Namespace (dns, url, oid, x500, or custom UUID)
- `--name <NAME>`: Name to hash (required)

```bash
mkid uuid v5 --namespace dns --name example.com
# Output is deterministic: same namespace + name = same UUID
```

**For v8 (custom):**
- `--bytes <HEX>`: 32 hex characters (16 bytes)

```bash
mkid uuid v8 --bytes 0123456789abcdef0123456789abcdef
```

### Output Formats

```bash
# Hyphenated (default)
mkid uuid v7 --format hyphenated
# 019c0edc-d74c-7c02-beb9-40fcf2eee5f6

# Simple (no hyphens)
mkid uuid v7 --format simple
# 019c0edcd74c7c02beb940fcf2eee5f6

# URN
mkid uuid v7 --format urn
# urn:uuid:019c0edc-d74c-7c02-beb9-40fcf2eee5f6

# Braced
mkid uuid v7 --format braced
# {019c0edc-d74c-7c02-beb9-40fcf2eee5f6}
```

### Case Control

```bash
# Uppercase
mkid uuid v7 --uppercase
# 019C0EDC-D74C-7C02-BEB9-40FCF2EEE5F6

# Lowercase (default)
mkid uuid v7
# 019c0edc-d74c-7c02-beb9-40fcf2eee5f6
```

### Bulk Generation

```bash
# Generate 5 UUIDs
mkid uuid v7 --count 5
# 019c0edd-19ee-7903-8ec0-cc2098967b15
# 019c0edd-19ee-7903-8ec0-cc324e67abd2
# 019c0edd-19ee-7903-8ec0-cc4871c57653
# 019c0edd-19ee-7903-8ec0-cc552b063bff
# 019c0edd-19ee-7903-8ec0-cc6150da757c
```

Note: v7 UUIDs are monotonic (sortable by generation time).

### Clipboard Integration

```bash
# Copy to clipboard
mkid --clipboard
mkid uuid v7 --clipboard

# Copy multiple UUIDs (newline-separated)
mkid uuid v4 --count 5 --clipboard
```

### Combining Options

```bash
# Multiple options at once
mkid uuid v7 --uppercase --format simple --count 3 --clipboard
# 019C0EDD08B37C42AABE599AEA317DE1
# 019C0EDD08B37C42AABE599D2F5B8A92
# 019C0EDD08B37C42AABE599E5C9A1B23
# (also copied to clipboard)
```

## Why UUID v7?

UUID v7 is the default because it provides:

1. **Database performance**: Time-ordered UUIDs reduce B-tree fragmentation (up to 10x better than v4)
2. **Sortability**: Lexicographic comparison works directly on the UUID bytes
3. **Modern timestamps**: Uses Unix epoch in milliseconds (familiar to developers)
4. **Monotonicity**: Sequential UUIDs are guaranteed to be ordered
5. **No clock drift issues**: Better than v1/v6 for distributed systems

## UUID Version Comparison

| Version | Type | Use Case | Deterministic |
|---------|------|----------|---------------|
| v1 | Time + Node | Legacy systems | No |
| v3 | MD5 hash | Namespace-based (legacy) | Yes |
| v4 | Random | General purpose | No |
| v5 | SHA-1 hash | Namespace-based | Yes |
| v6 | Sortable time | Database keys (modern) | No |
| v7 | Timestamp | Database keys (recommended) | No |
| v8 | Custom | Special requirements | Depends |

## Examples

### Generate API keys
```bash
mkid uuid v4 --format simple --uppercase
```

### Generate sortable database IDs
```bash
mkid uuid v7 --count 100
```

### Generate deterministic UUIDs for testing
```bash
mkid uuid v5 --namespace dns --name test-user-1
mkid uuid v5 --namespace dns --name test-user-2
```

### Quick clipboard workflow
```bash
mkid -c  # Generate v7 and copy to clipboard
# Paste anywhere: Cmd+V (macOS) or Ctrl+V (Linux/Windows)
```

## Testing

Run the test suite:

```bash
cargo test
```

The project includes comprehensive integration tests covering:
- All UUID versions
- Format options
- Deterministic behavior (v3/v5)
- Monotonicity (v7)
- Error handling
- Count functionality

## Future Plans

The architecture supports future addition of other ID formats:
- ULID (Universally Unique Lexicographically Sortable Identifier)
- NanoID (URL-friendly unique ID)
- Snowflake (Twitter's distributed ID)
- CUID (Collision-resistant Unique ID)

Example future usage:
```bash
mkid ulid
mkid nanoid
mkid snowflake
```

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contributing

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

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
