docs(cli): object and array-of-object params do work via CLI - #646
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.
kriszyp
left a comment
kriszyp
left a comment
There was a problem hiding this comment.
Sounds good
🤖 Reviewed with Codex
| <!-- Source: Harper CLI source code (SUPPORTED_OPS and OP_ALIASES arrays) --> | ||
|
|
||
| The following operations are available through the CLI. Operations that require complex nested parameters or object structures are not supported via CLI and must be executed through the HTTP API. | ||
| The following operations are available through the CLI. Argument values are JSON-parsed, so operations that take nested objects or arrays of objects work from the CLI as well. See [Parameter Formatting](#parameter-formatting) for how to quote them. |
There was a problem hiding this comment.
This page now correctly says nested parameters work, but reference/cli/overview.md:120 still tells readers that Operations API commands are limited to operations without complex nested parameters. That linked landing page will continue to steer the affected users away; update it with this correction.
|
|
||
| Every argument is split on the first `=` and the value is parsed as JSON. If the value is not valid JSON, it is passed through unchanged as a string. That single rule covers all of the parameter types below: `database=dev` fails to parse and stays the string `"dev"`, `json=true` parses to the boolean `true`, and `ids='["1","2"]'` parses to an array. | ||
|
|
||
| The one exception is `ref` (used by deploy-by-reference), which is always taken as a raw string so that a numeric-looking git tag such as `ref=1.0` is not rewritten into the number `1`. |
There was a problem hiding this comment.
This exception is only true from v5.2.3: v5.2.0-v5.2.2 still JSON-parse ref=1.0 to 1. Current Reference is consolidated v5 documentation, so mark this behavior change with its availability or qualify it as v5.2.3+; otherwise users on earlier v5.2 patch releases get a command that resolves the wrong ref.
|
|
||
| - The [Operations API](../operations-api/overview.md) via HTTP | ||
| - A custom script or tool | ||
| `harper deploy setup=true` prints exactly this `credentials='[...]'` form as the command to run after it seals a registry or git token, so an array-of-objects argument is the normal path for private-package deploys rather than an edge case. |
There was a problem hiding this comment.
harper deploy setup=true was also introduced in v5.2.3. Qualify this workflow as v5.2.3+ (or add the appropriate availability marker), so users on earlier v5.2 releases do not rely on a credential-provisioning path their CLI does not provide.
| - Operations with array-of-objects parameters | ||
| - File upload operations | ||
| - Streaming operations | ||
| - **Raw binary bodies.** An argument value is text, so an operation whose request body is raw binary has no general CLI form. The two that need one have dedicated handling: `deploy_component` packages and uploads the current directory when `package` is omitted, and `get_backup` streams the snapshot to a file. Any other binary payload has to go over HTTP. |
There was a problem hiding this comment.
get_backup does not require a raw binary request body: the CLI sends a normal JSON request and streams the binary response to out. Grouping it under “Raw binary bodies” contradicts the preceding description and obscures the real boundary. Split request-body limitations from binary-response handling, or describe this as binary-transfer support.
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
3 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