1 files changed, 118 insertions, 0 deletions
diff --git a/cli/README.md b/cli/README.md
new file mode 100644
index 0000000..478c178
--- /dev/null
+++ b/cli/README.md
@@ -0,0 +1,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).