docs(cli): object and array-of-object params do work via CLI - #646
docs(cli): object and array-of-object params do work via CLI#646Ethan-Arrowood wants to merge 2 commits into
Conversation
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-646 This preview will update automatically when you push new commits. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the CLI operations API documentation to clarify that nested objects and arrays of objects are supported via JSON-parsed argument values. It adds detailed explanations of parameter formatting, quoting rules, and security warnings regarding command-line arguments, while updating the limitations section to accurately reflect constraints like raw binary bodies and large payloads. There are no review comments, so no feedback is provided.
The Operations API commands page asserted in three places that nested objects and arrays of objects cannot be passed as CLI arguments. That is not true, and the page contradicted itself: it showed a working `ids='["1","2","3"]'` array a few lines above the claim. `buildRequest()` in `bin/cliOperations.ts` JSON-parses every argument value, falling back to the raw string when the parse throws. Scalars, arrays, and objects all take that one path, so there is no basis for treating objects differently. `RAW_STRING_FIELDS` is `new Set(['ref'])` -- `ref` is the sole field exempted from the parse, so a numeric-looking git tag is not rewritten into a number. - State the actual parse rule once, at the top of Parameter Formatting, and note the `ref` exception. - Replace the "objects not supported" section with the `deploy_component` `credentials` array-of-objects example that `harper deploy setup=true` itself prints, plus the shell quoting rules that do apply. - Rewrite Limitations around real constraints: raw binary bodies, the OS argument-length cap, and secrets being visible in shell history, `ps`, and CI logs. Drop the false nested-JSON and array-of-objects entries, and the "file upload / streaming" entries that `deploy_component` and `get_backup` disprove. Closes #639 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The `deploy_component` example linked to `github.com/HarperDB/application-template`, which now only resolves via the org-rename redirect. Verified `HarperFast/application-template` exists and is not archived (`gh repo view`), so the canonical URL is used directly. The other two GitHub URLs on the page (`user/repo`, `myorg/my-component`) are deliberate placeholders and are unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
a475341 to
1300a1d
Compare
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-646 This preview will update automatically when you push new commits. |
dawsontoth
left a comment
dawsontoth
left a comment
There was a problem hiding this comment.
Very helpful for understanding how it works, nice.
2 participants
What
reference/cli/operations-api-commands.mdasserted in three places that nested objects and arrays of objects cannot be passed as CLI arguments. They can, and the page contradicted itself: it showed a workingids='["1","2","3"]'array a few lines above the "objects not supported" text.Verified against
harper@origin/main:bin/cliOperations.ts—buildRequest()splits eachargventry on the first=andJSON.parses the value, falling back to the raw string when the parse throws. Scalars, arrays, and objects all take that one path, so there is no code basis for treating objects differently from the array example already on the page.bin/cliOperations.ts—RAW_STRING_FIELDSisnew Set(['ref']).refis the only field exempted from the parse (added soref=1.0is not rewritten into the number1, then the tag"1"). The exception list has not grown.bin/deploySetup.tsprintscredentials='${JSON.stringify([credentialEntry])}'as the recommended command after sealing a git or npm token, i.e. an array-of-objects CLI argument is the documented happy path, not an edge case.bin/backup.ts—runBackupCommand()/downloadBackup()streamsget_backupto a file, andPREPARE_OPERATION.deploy_componentincliOperations.tsdoes a multipart upload with SSE progress. Both disprove the old "File upload operations / Streaming operations" limitation entries.Changes
Restricted to
reference/cli/operations-api-commands.mdonly (avoiding overlap with #624).refexception.deploy_componentcredentialsexample, the shell quoting rules that genuinely apply (single quotes, one argument, embedding a literal'), and a warning that arguments are visible in shell history,ps, and CI logs.Checks
npm run format:checkcleannpm run buildsucceeds (the two reported broken anchors are pre-existing, inbackups/overviewandrelease-notes/v5-lincoln/5.1, and unrelated to this file)Closes #639
🤖 Generated with Claude Code