packages/cli/README.md:7 says the CLI "supports four command namespaces" and then lists connect, owner-agent, collector, and ref. The count has drifted. read, package-info, and token are all dispatched in src/index.ts and all appear in --help, so the README is missing three of them.
read is the interesting omission. It is the whole grant-scoped query path, implemented in packages/cli/src/read/commands.ts with seven subcommands (schema, streams, query-records, fetch, field-window, search, aggregate), and a reader of the README would not know it exists.
Fix the namespace count and list, then give read a section with copyable examples for each subcommand. Worth stating explicitly somewhere in that section: reads use the grant cache that pdpp connect writes to a project-local .pdpp directory, not owner credentials. The file header at commands.ts:17 says so, and it is the part people get wrong.
A few flags are parsed but missing from readHelp() at commands.ts:16-25:
--changes-since and --order on query-records (parsed at L115 and L112)--time-zone on aggregate (L188)--cursor on search (L168) and field-window (L145). It is already documented for query-records, so this is a per-subcommand gap rather than a missing flag.
Please leave --connector-instance-id alone. It is a deprecated wire alias and test/read.test.ts:35 asserts it stays out of the help text, so documenting it would break a passing test on purpose.
No new CLI behavior here. Everything above already works, it is just undocumented.
pnpm --filter @pdpp/cli test
The check I care about is that every example you write actually runs against the current parser. Please paste real terminal output into the PR rather than hand-writing the examples.
packages/cli/README.md:7says the CLI "supports four command namespaces" and then listsconnect,owner-agent,collector, andref. The count has drifted.read,package-info, andtokenare all dispatched insrc/index.tsand all appear in--help, so the README is missing three of them.readis the interesting omission. It is the whole grant-scoped query path, implemented inpackages/cli/src/read/commands.tswith seven subcommands (schema,streams,query-records,fetch,field-window,search,aggregate), and a reader of the README would not know it exists.Fix the namespace count and list, then give
reada section with copyable examples for each subcommand. Worth stating explicitly somewhere in that section: reads use the grant cache thatpdpp connectwrites to a project-local.pdppdirectory, not owner credentials. The file header atcommands.ts:17says so, and it is the part people get wrong.A few flags are parsed but missing from
readHelp()atcommands.ts:16-25:--changes-sinceand--orderonquery-records(parsed at L115 and L112)--time-zoneonaggregate(L188)--cursoronsearch(L168) andfield-window(L145). It is already documented forquery-records, so this is a per-subcommand gap rather than a missing flag.Please leave
--connector-instance-idalone. It is a deprecated wire alias andtest/read.test.ts:35asserts it stays out of the help text, so documenting it would break a passing test on purpose.No new CLI behavior here. Everything above already works, it is just undocumented.
The check I care about is that every example you write actually runs against the current parser. Please paste real terminal output into the PR rather than hand-writing the examples.