From b889da6e19e781ff5d1372384df7df414b63fd2b Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Thu, 27 Aug 2026 14:36:07 -0600 Subject: [PATCH 1/2] docs(cli): object and array-of-object params do work via CLI 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 --- reference/cli/operations-api-commands.md | 37 +++++++++++++++++------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/reference/cli/operations-api-commands.md b/reference/cli/operations-api-commands.md index 8d128e8b..f8bf60cd 100644 --- a/reference/cli/operations-api-commands.md +++ b/reference/cli/operations-api-commands.md @@ -26,7 +26,7 @@ harper = -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. ### Complete Operations List @@ -282,6 +282,10 @@ For more information on Harper applications and components, see: ## Parameter Formatting +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`. + ### String Parameters Simple string values can be passed directly: @@ -300,10 +304,24 @@ harper search_by_id database=dev table=dog ids='["1","2","3"]' ### Object Parameters -Object parameters are not supported via CLI. For operations requiring complex nested objects, use: +Objects and arrays of objects are supported. Pass them as single-quoted JSON: + +```bash +harper deploy_component project=my-app package=npm:@my-org/my-app@1.2.3 \ + credentials='[{"registry":"registry.my-org.com","secret":"deploy.my-app.registry.my-org.com"}]' +``` -- 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. + +Quoting rules: + +- Wrap the JSON in **single** quotes. Double quotes let the shell expand `$`, backticks, and history references inside the value; single quotes pass the JSON through intact. +- The whole `key=value` pair is one shell argument, so no unescaped spaces outside the quotes. Compact JSON with no spaces after `:` and `,` avoids the problem entirely. +- To embed a literal single quote inside the JSON, end the quoted run, escape it, and reopen: `'{"name":"O'\''Brien"}'`. + +:::warning +Command-line arguments are not private. Anything you type appears in shell history, in process listings (`ps`), and in CI job logs. Prefer a stored secret reference (the `secret` field above) or an environment variable over inlining a plaintext token in an argument. +::: ### Boolean Parameters @@ -369,14 +387,13 @@ harper get_components \ ## Limitations -The following operation types are **not supported** via CLI: +Nested objects and arrays of objects are **not** a limitation; see [Object Parameters](#object-parameters). The real constraints are about what an argument value can carry: -- Operations requiring complex nested JSON structures -- 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. +- **Large payloads.** There is no way to feed an argument value from stdin or a file, and the operating system caps total argument length. Bulk data such as an inline `csv_data_load` is better sent over HTTP. +- **Secrets on the command line.** Arguments are visible in shell history, `ps` output, and CI logs. Use a stored secret reference or an environment variable instead of an inline token. -For these operations, use the [Operations API](../operations-api/overview.md) directly via HTTP. +For these cases, use the [Operations API](../operations-api/overview.md) directly via HTTP. ## See Also From 1300a1df7336a9d4d9996e36a9530a0360eb338f Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Thu, 27 Aug 2026 14:57:28 -0600 Subject: [PATCH 2/2] docs(cli): point application-template at HarperFast 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 --- reference/cli/operations-api-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/cli/operations-api-commands.md b/reference/cli/operations-api-commands.md index f8bf60cd..08e287af 100644 --- a/reference/cli/operations-api-commands.md +++ b/reference/cli/operations-api-commands.md @@ -204,7 +204,7 @@ For comprehensive configuration options, see the [Configuration Reference](../co **Deploy a component**: ```bash -harper deploy_component project=my-cool-app package=https://github.com/HarperDB/application-template +harper deploy_component project=my-cool-app package=https://github.com/HarperFast/application-template ``` **Get all components**: