idt 0.1.1

A fast, ergonomic CLI tool for working with various ID formats
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

# inspect - Analyze IDs

Analyze and decode identifiers to extract embedded information like timestamps, versions, and other metadata.

## Usage

```bash
idt inspect [OPTIONS] [ID]...
```

## Arguments

| Argument | Description |
|----------|-------------|
| `ID` | ID(s) to inspect (reads from stdin if omitted) |

## Options

| Option | Description |
|--------|-------------|
| `-t, --type <TYPE>` | Hint the ID type (skip auto-detection) |
| `-q, --quiet` | Only show errors (for validation use) |

## Output Fields

When inspecting an ID, idt displays:

| Field | Description |
|-------|-------------|
| Type | Detected ID type (e.g., UUIDV7, ULID) |
| Canonical | The ID in its canonical format |
| Time | Embedded timestamp (if available) |
| Version | UUID version number (for UUIDs) |
| Variant | UUID variant (for UUIDs) |
| Random | Number of random bits |
| Hex | Hexadecimal encoding |
| Base64 | Base64 encoding |
| Int | Integer representation |

## Examples

### Basic Inspection

```bash
# Inspect a UUID
idt inspect 550e8400-e29b-41d4-a716-446655440000

# Inspect a ULID
idt inspect 01ARZ3NDEKTSV4RRFFQ69G5FAV

# Inspect multiple IDs
idt inspect 550e8400-e29b-41d4-a716-446655440000 01ARZ3NDEKTSV4RRFFQ69G5FAV
```

### Example Output

```bash
$ idt inspect 019c04e5-6118-7b22-95cb-a10e84dad469
UUIDV7
  019c04e5-6118-7b22-95cb-a10e84dad469

  Time       2026-01-28T13:57:47.416Z
  Version    7
  Variant    RFC4122
  Random     62 bits

  Hex        019c04e561187b2295cba10e84dad469
  Base64     AZwE5WEYeyKVy6EOhNrUaQ==
  Int        2139325608653621017571381452845274217
```

### ULID Output

```bash
$ idt inspect 01ARZ3NDEKTSV4RRFFQ69G5FAV
ULID
  01ARZ3NDEKTSV4RRFFQ69G5FAV

  Time       2016-07-30T23:54:10.259Z
  Random     80 bits

  Hex        01563e3ab5d3d6764c61efb99302bd5b
  Base64     AVY+OrXT1nZMYe+5kwK9Ww==
  Int        1777027686520646174104517696511196507
```

### Type Hints

When auto-detection is ambiguous, provide a type hint:

```bash
# Force interpretation as UUID
idt inspect -t uuid 550e8400e29b41d4a716446655440000
```

### Reading from stdin

```bash
# Pipe from gen command
idt gen uuidv7 | idt inspect

# Read multiple IDs from file
cat ids.txt | idt inspect

# Here-string
idt inspect <<< "550e8400-e29b-41d4-a716-446655440000"
```

### JSON Output

```bash
# JSON output
idt inspect 550e8400-e29b-41d4-a716-446655440000 --json

# Pretty-printed JSON
idt inspect 550e8400-e29b-41d4-a716-446655440000 --json --pretty
```

Example JSON output:

```json
{
  "id_type": "uuidv4",
  "canonical": "550e8400-e29b-41d4-a716-446655440000",
  "version": "4",
  "variant": "RFC4122",
  "random_bits": 122,
  "encodings": {
    "hex": "550e8400e29b41d4a716446655440000",
    "base64": "VQ6EAOKbQdSnFkRmVUQAAA==",
    "int": "113059749145936325402354257176981405696"
  }
}
```

### Quiet Mode

Quiet mode exits with code 0 for valid IDs, 1 for invalid:

```bash
if idt inspect -q "$ID" 2>/dev/null; then
    echo "Valid and parseable"
fi
```

### Inspecting Generated IDs

```bash
# Generate and inspect in one pipeline
idt gen uuidv7 | idt inspect

# Generate multiple and inspect
idt gen ulid -n 5 | idt inspect
```