Files

teernisse e3d2e9306b Document TUI controls, category synonyms, flag aliases, and compare JSON

AGENTS.md:
- Add command table covering all five commands
- Expand input tolerance section with flag alias table
- Add filtering/sorting, auto JSON, and structured error sections
- Include canonical examples for compare

README.md:
- Expand compare command docs with ranking explanation and --count flag
- Replace tui stub with full keybinding reference (tab, /, s, g, c, a,
  l, r, [/], 1-9, u/d, b/f, ?, q)
- Add compare-specific flags section and sort alias note
- Add category synonym table showing all bidirectional mappings
- Add flag alias resolution table (zipcode->zip, dept->department, etc.)
- Add compare JSON schema documenting all response fields

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-23 01:32:18 -05:00

2.1 KiB

Raw Blame History

Agent CLI Notes

The pubcli CLI is intentionally tolerant of minor syntax mistakes when intent is clear.

Commands

Command	Purpose	Requires
`pubcli`	Fetch deals	`--store` or `--zip`
`pubcli stores`	List nearby stores	`--zip`
`pubcli categories`	List categories with counts	`--store` or `--zip`
`pubcli compare`	Rank nearby stores by deal quality	`--zip`
`pubcli tui`	Interactive deal browser	`--store` or `--zip`, interactive terminal

Input Tolerance

Accepted flexible forms include:

-zip 33101 -> interpreted as --zip 33101
zip=33101 -> interpreted as --zip=33101
--ziip 33101 -> interpreted as --zip 33101
categoriess -> interpreted as categories

Flag aliases: zipcode/postal-code -> --zip, dept -> --department, search -> --query, sortby/orderby -> --sort, max -> --limit.

The CLI prints a note: line when it auto-corrects input. Use canonical syntax in future commands:

pubcli --zip 33101
pubcli --store 1425 --bogo
pubcli categories --zip 33101
pubcli stores --zip 33101 --json
pubcli compare --zip 33101 --category produce
pubcli compare --zip 33101 --bogo --count 3 --json

Filtering and Sorting

Deal filter flags (--bogo, --category, --department, --query, --sort, --limit) are available on pubcli, compare, and tui.

Sort accepts: relevance (default), savings, ending. Aliases end, expiry, expiration map to ending.

Category synonyms: veggies -> produce, chicken -> meat, bread -> bakery, cheese -> dairy, cold cuts -> deli, etc.

Auto JSON

When stdout is not a TTY, JSON output is enabled automatically. This means piping to jq or another process produces JSON without requiring --json.

Errors

When intent is unclear, errors include a direct explanation and relevant examples. In JSON mode, errors are structured:

{"error":{"code":"INVALID_ARGS","message":"...","suggestions":["..."],"exitCode":2}}

Exit codes: 0 success, 1 not found, 2 invalid args, 3 upstream error, 4 internal error.

2.1 KiB Raw Blame History