Upgrade libby CLI

README.md

@@ -107,3 +107,100 @@ keyword registry:
   sorted. `%` wildcards within a single name.
 - `keys.describe` — payload `{"name": "..."}` → flat metadata dict.
   Exact lookup; no wildcards.
+
+## CLI
+
+`libby` is the command-line front for keyword peers. Verbs:
+
+```
+libby show     <group>.<scope>.<name>     # read a keyword (% wildcard in name)
+libby modify   <group>.<scope>.<name>=V   # write a keyword (exact name)
+libby list     <group>.<scope>.<pattern>  # list keyword names (% wildcard in name)
+libby describe <group>.<scope>.<name>     # metadata for one keyword (exact name)
+```
+
+`<group>.<scope>` is the address of one peer (`peer_id` =
+`<group>_<scope>`). Cross-peer fanout is not supported. `req` and `sub`
+are kept for raw RPC / topic debugging.
+
+### Examples
+
+```
+$ libby show hsfei.pickoff.positionvalue
+hsfei.pickoff.positionvalue = 79.0 mm
+
+$ libby show hsfei.pickoff.is%
+hsfei.pickoff.isconnected   = True
+hsfei.pickoff.isloopclosed  = True
+hsfei.pickoff.ismoving      = False
+hsfei.pickoff.isreferenced  = True
+
+$ libby modify hsfei.pickoff.softmax=120
+hsfei.pickoff.softmax = 120.0 mm
+
+$ libby modify hsfei.pickoff.softmax=null   # or hsfei.pickoff.softmax=
+hsfei.pickoff.softmax = None mm
+
+$ libby describe hsfei.pickoff.positionvalue
+hsfei.pickoff.positionvalue:
+  type         float
+  readonly     False
+  writeonly    False
+  nullable     False
+  units        mm
+  description  Stage position in engineering units.
+
+$ libby list hsfei.pickoff.%min
+hsfei.pickoff.hardmin
+hsfei.pickoff.softmin
+```
+
+Add `--json` to any verb for machine-readable output (objects for
+`show` / `modify` / `describe`, list of objects for `show <pattern>`,
+list of strings for `list`).
+
+### Modify syntax
+
+- `key=value` or `key value` (positional) both work.
+- Empty (`key=`) and `null` clear nullable values.
+- Coercion is heuristic: `true` / `false` → bool, integer-looking →
+  int, decimal-looking → float, else string.
+
+### Config
+
+The CLI looks for `~/.libby/cli_config.yaml` by default; override the
+path per call with `--config <path>`. An example template ships with
+the package at `libby/cli/cli_config.example.yaml` — copy it and
+edit:
+
+```bash
+mkdir -p ~/.libby
+cp $(python -c "import libby.cli, os; print(os.path.dirname(libby.cli.__file__))")/cli_config.example.yaml ~/.libby/cli_config.yaml
+```
+
+Schema:
+
+```yaml
+transport: rabbitmq          # zmq | rabbitmq
+rabbitmq_url: amqp://localhost
+
+# Used only when transport=zmq:
+peers:
+  hsfei_pickoff: tcp://hispec.caltech.edu:5555
+```
+
+All keys are optional. Missing file is fine — defaults are
+`transport: rabbitmq` / `rabbitmq_url: amqp://localhost`.
+
+Precedence: `--transport` / `--rabbitmq-url` flags override yaml; yaml
+overrides built-in defaults. Flags must appear *after* the subcommand
+(`libby show --transport zmq foo`, not the other way).
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | success |
+| 1 | argument / parse error |
+| 2 | RPC or response error (e.g. read-only, unknown keyword, transport failure) |
+| 3 | wildcard `list` / `show` matched no keywords |

libby/cli/cli_config.example.yaml

@@ -0,0 +1,15 @@
+# Example libby CLI config.
+#
+# Copy this to ~/.libby/cli_config.yaml and edit as needed:
+#   mkdir -p ~/.libby
+#   cp <libby_pkg>/cli/cli_config.example.yaml ~/.libby/cli_config.yaml
+#
+# All keys are optional. Built-in defaults match what's shown here.
+# Override per-call with --config / --transport / --rabbitmq-url flags.
+
+transport: rabbitmq
+rabbitmq_url: amqp://localhost
+
+# ZMQ address book (peer_id -> tcp://host:port). Only consulted when
+# transport=zmq. Leave empty for RabbitMQ deployments.
+peers: {}