# 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).