zhtmldb

Persist and query agent data with zhtmldb using $ARGUMENTS. Apply all rules below.

What is zhtmldb

zhtmldb is a key-value datastore whose storage format is also its UI: every record is a valid XHTML page (<table>/<key>.html) holding its fields as <dt>/<dd> pairs, and every table folder plus the root carries a generated index.html. The database is a folder that a browser renders, git diff tracks per record and an XML parser reads. One executable script, no server, no libraries.

• Source: https://github.com/AdamBien/zhtmldb
• Requires: Java 25+ on PATH (java -version)

Setup

Check for the tool before the first command; install it when missing:

command -v zhtmldb || {
  curl -O https://raw.githubusercontent.com/AdamBien/zhtmldb/main/zhtmldb
  chmod +x zhtmldb
  sudo cp zhtmldb /usr/local/bin/
}
zhtmldb -help

The database root is the current directory unless db.dir is set. Decide the root deliberately before the first write, so records do not land in whatever directory the shell happens to be in:

• Project data: run from the project root, or put db.dir=<path> into ./app.properties.
• Agent memory across projects: ~/.zhtmldb/app.properties with db.dir=/path/to/memory.
• One-off: java -Ddb.dir=<path> --source 25 /usr/local/bin/zhtmldb <table> <command> ...

Precedence is global file, then local file, then -D; the last one wins.

Command Contract

zhtmldb <table> set <key> <field>=<value>...   store fields, merged into the record
zhtmldb <table> set <key> <field>+=<value>     append, newline separated
zhtmldb <table> set <key> <field>              value from stdin (<field>+ appends)
zhtmldb <table> set <key> "<v1,v2,...>"        positional by declared columns
zhtmldb <table> add <value>...                 new record under a timestamp key
zhtmldb <table> columns <name,name,...>        declare column order (once per table)
zhtmldb <table> get <key> [field]              field<TAB>value lines, or one value
zhtmldb <table> rm <key> [field]               remove a record, or one field
zhtmldb <table> keys                           sorted keys
zhtmldb <table> find <term>...                 key<TAB>label, for piping
zhtmldb <table> list [<term>...]               aligned table, for reading
zhtmldb tables