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
|
# ugi-cli
Command-line tool for encoding, decoding, and converting UGI (Unified Geek Identifier) strings.
## Dependencies
- **bash** 4.0+
- **jq** — [jqlang.github.io/jq](https://jqlang.github.io/jq/)
- **ugi_registry_v0.json** — from [ugi-spec](https://git.sr.ht/~gumxcc/ugi-spec)
## Setup
```bash
git clone https://git.sr.ht/~gumxcc/ugi-cli
cd ugi-cli
# Point to the registry (pick one):
export UGI_REGISTRY=/path/to/ugi_registry_v0.json
# or place/symlink it next to the script:
ln -s /path/to/ugi-spec/ugi_registry_v0.json .
```
Optionally add to `$PATH`:
```bash
ln -s "$PWD/ugi" ~/.local/bin/ugi
```
## Usage
### Decode
Parse a UGI string into a human-readable table:
```
$ ugi decode "ugi:0@jdoe:gcs$/dev,a4,b5/4,ppy6$js6ts5,i5"
Version: 0
Handle: @jdoe
Field Code Decoded
----------------------------------------------------------------------
Geek Specialization g Computer Science ($), dev
Age a4 25-34
Build b5/4 height: Above average; width: Average
Programming Languages p Python=Advanced / daily [$], JavaScript=Advanced / daily, TypeScript=Competent
AI Stance i5 Positive
```
Reads from stdin if no argument given:
```bash
echo "ugi:0@jdoe:gcs,a4" | ugi decode
```
### Convert
Convert between URI and block format:
```bash
# URI → Block
ugi convert "ugi:0@jdoe:gcs/dev,a4,ppy6rs5"
# Block → URI
ugi convert <<'EOF'
------- BEGIN UGI BLOCK -------
v:0 @jdoe Gcs/dev
A4
Ppy6 Prs5
-------- END UGI BLOCK --------
EOF
```
### Encode
Interactive guided encoder:
```bash
ugi encode
```
### Fields
List all field codes:
```bash
ugi fields
```
### Short aliases
```bash
ugi d "ugi:0@jdoe:gcs,a4" # decode
ugi c "ugi:0@jdoe:gcs,a4" # convert
ugi e # encode
ugi f # fields
```
## Testing
Run the test suite against the shared test cases from [ugi-spec](https://git.sr.ht/~gumxcc/ugi-spec):
```bash
./test.sh /path/to/ugi_registry_v0.json /path/to/ugi-spec/tests/cases.json
```
The test runner validates decode output (version, handle, field labels) and convert roundtrip (URI → Block → URI) for each case.
## Environment
| Variable | Description |
|---|---|
| `UGI_REGISTRY` | Path to `ugi_registry_v0.json`. Falls back to `./ugi_registry_v0.json` or `../ugi-spec/ugi_registry_v0.json`. |
## License
MIT — see [LICENSE](./LICENSE).
|
