@seliseblocks/cli-os 0.2.6 → 0.2.8

package/dist/skills/blocks-release-deployment/SKILL.md

@@ -1,81 +1,81 @@
----
-name: blocks-release-deployment
-description: "Trigger and inspect SELISE Blocks Release builds/deploys entirely through `blocks release *` — never raw fetch/curl; there is no SDK path (Release has no `@seliseblocks/client` namespace). Covers `release deploy` (auto-resolves the repo, verifies branch matches environment), `release status`/`builds get` (build lookup by id), and `builds list` (list builds for a repo). Use for 'deploy/trigger a release', 'check build status', 'list recent builds'. Always `--dry-run` before `--yes`. No artifact-upload capability — deploy triggers a configured pipeline only."
----
-
-# Blocks Release — Deployment
-
-Trigger and read Release builds through `blocks release *`. This is **100% CLI, no SDK equivalent** — `@seliseblocks/client` (`createBlocksClient()`) exposes only `auth`, `data`, `iam`, and `localization`; there is no `release` namespace anywhere in the SDK. Never write a frontend/app-code path for this — it's always a terminal command.
-
-**Prerequisite:** a project is selected (`blocks use <tenantId>`) and that project has a repo linked from the Blocks portal — see the blocks-onboarding skill. There is no local config file for release settings; `blocks init` only scaffolds `blocks/data/schemas/`, `blocks/data/rules.json`, and `.env.example` — it has no release-related output at all. `deploy` and `builds list` both resolve which repo to act on directly from the project's linked assets (see below), not from any file on disk.
-
-## Safe read commands
-
-- **`blocks release status <buildId> [--json]`** — one build's status by id (positional arg, or `--build-id <id>`).
-- **`blocks release builds get <buildId> [--json]`** — literally the same call as `release status`; it's a pure alias in the CLI's own source (`releaseBuildsGet` just calls `releaseStatus(argv)`), not a different endpoint or response shape. Use whichever name the user said.
-- **`blocks release builds list [<repoId>] [--repo-id <repoId>] [--json]`** — all builds for one repository. `repoId` is optional: if omitted, the CLI auto-resolves it from the selected project's linked repo assets the same way `deploy` does (see "Resolving the repo" below) — **except** when more than one repo is linked, in which case it falls back to an interactive `selectFromList()` prompt instead of erring or guessing. That prompt has no stdin in a non-interactive/agent run and will hang — if you can't guarantee a human is watching the terminal, resolve and pass `--repo-id` explicitly instead of letting this fall through to the prompt (the same hang risk applies to `blocks new web`'s OIDC-client picker when `--client-id` is omitted — always resolve and pass required values explicitly rather than relying on an interactive fallback).
-
-None of these mutate anything — safe to run without confirmation.
-
-## Mutating: trigger a deploy
-
-```bash
-blocks release deploy --dry-run --json   # show the exact request first
-blocks release deploy --yes --json       # only after the user approves
-```
-
-There is **no `--repo-id` flag on `deploy`** — the repo is always resolved automatically (see below); passing `--repo-id` is not recognized by this command.
-
-### Resolving the repo
-
-`deploy` never takes a repo id as input. It resolves one from the currently selected project's linked assets:
-
-1. It looks up the project's linked repo resources for the project's `tenantGroupId`.
-2. If exactly one repo is linked, that's the one used.
-3. If multiple are linked, it picks the one whose asset `name` matches the project's `environment` (case-insensitive); if none matches, it throws `repo_ambiguous`.
-4. If none are linked at all, it throws `repo_not_linked`.
-
-### Branch/environment safety check
-
-Before building, `deploy` fetches the resolved repo's details to read its linked branch, then compares that branch to the project's `environment` (case-insensitive). If they don't match, it throws `branch_environment_mismatch` rather than building the wrong branch.
-
-### Error codes you may see
-
-| Code | Meaning | Fix |
-|---|---|---|
-| `repo_not_linked` | No repo is linked to this project at all. | Link a repo from the Blocks portal (requires GitHub OAuth), then re-run. |
-| `repo_ambiguous` | Multiple repos are linked and none is named for the project's `environment`. | Check the repo links for this project from the Blocks portal. |
-| `repo_not_found` | The linked asset's repo id wasn't found in blocks-release when fetching repo details. | Check the repo link for this project from the Blocks portal. |
-| `branch_environment_mismatch` | The linked repo's branch doesn't match the project's `environment` (e.g. repo is on `main` but environment is `staging`). Message states the branch found and the environment required. | Point the linked repo at a branch named for the environment, or relink the correct branch from the Blocks portal. |
-| `build_wait_timeout` | Only with `--wait`: no terminal build status was seen before `--timeout` elapsed. | Check manually with `blocks release status <buildId>`. |
-
-### Optional flags
-
-- **`--domain <domain>`** — before triggering the build, makes an extra call to set a custom deployment domain for this repo/environment.
-- **`--wait`** — after triggering, polls the build status (by the returned `buildId`) every `--poll-interval` seconds until the status matches a terminal pattern (succeeded/success/completed/failed/error/cancelled/aborted/done, case-insensitive) or `--timeout` elapses (then throws `build_wait_timeout`).
-- **`--poll-interval <seconds>`** — polling interval for `--wait`, default `10`.
-- **`--timeout <seconds>`** — max time to wait for `--wait`, default `900`.
-
-`--dry-run` prints the resolved `repoId`, `branch`, `environment`, `projectKey`, and (if given) `domain` — it does **not** build a request body from any local file, since none exists. The real request when not a dry run is simply `{ repoId }`. Always show the `--dry-run` output and get explicit approval before re-running with `--yes` — never skip straight to `--yes`.
-
-## Gotchas
-
-- **No SDK path, ever.** If asked "how do I trigger a deploy from my app," the answer is: you don't — this is a CLI-only, human/CI-operated action, not something to wire into frontend code.
-- **No artifact upload.** `release deploy` triggers a *configured* pipeline/repository build — it does not accept or upload a build artifact you hand it. If a user asks to "upload my build and deploy it," that capability doesn't exist in this CLI; say so rather than inventing an upload flag.
-- **`release builds get` and `release status` are the same command.** Don't treat them as returning different data or document them separately — the CLI's own source has `builds get` call `release status` directly.
-- **Release commands are project-scoped, not account-level.** `deploy`, `status`, and `builds list` all run on an impersonated project token, and `deploy`/`builds list` both resolve which project's linked assets to use from whichever project is currently selected via `blocks use`. Behavior changes if the selected project changes; there is no account-level/project-independent mode here.
-- **`deploy` never takes a repo id from the user** — it's always auto-resolved from the project's linked assets, with a real branch/environment safety check before it will build. Don't offer or accept a `--repo-id` flag on `deploy`.
-- **`builds list --repo-id` is optional, not required** — it falls back to the same auto-resolve logic as `deploy`, but that fallback can hit an interactive prompt if multiple repos are linked. Pass `--repo-id` explicitly in any non-interactive/agent context to avoid the hang.
-- **`buildId` for `status`/`builds get` is always required**, never guessed — ask the user rather than assuming a value.
-- **`--dry-run` before `--yes`, always** — same discipline as every other mutating `blocks` command in this pack.
-
-## Example trigger prompts
-
-- "Deploy this project's configured release."
-- "Trigger a build for the linked repo."
-- "Check the status of build `<buildId>`."
-- "Did my last deploy finish? Look up build `<buildId>`."
-- "List the recent builds for this repo."
-- "Deploy and wait until it finishes." → add `--wait` (optionally `--poll-interval`/`--timeout`).
-- "Deploy this to a custom domain." → add `--domain <domain>`.
-- "Can you upload my compiled artifact and deploy it?" → not supported; explain there's no artifact-upload path, only triggering the repo's configured pipeline.
+---
+name: blocks-release-deployment
+description: "Trigger and inspect SELISE Blocks Release builds/deploys entirely through `blocks release *` — never raw fetch/curl; there is no SDK path (Release has no `@seliseblocks/client` namespace). Covers `release deploy` (auto-resolves the repo, verifies branch matches environment), `release status`/`builds get` (build lookup by id), and `builds list` (list builds for a repo). Use for 'deploy/trigger a release', 'check build status', 'list recent builds'. Always `--dry-run` before `--yes`. No artifact-upload capability — deploy triggers a configured pipeline only."
+---
+
+# Blocks Release — Deployment
+
+Trigger and read Release builds through `blocks release *`. This is **100% CLI, no SDK equivalent** — `@seliseblocks/client` (`createBlocksClient()`) exposes only `auth`, `data`, `iam`, and `localization`; there is no `release` namespace anywhere in the SDK. Never write a frontend/app-code path for this — it's always a terminal command.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`) and that project has a repo linked from the Blocks portal — see the blocks-onboarding skill. There is no local config file for release settings; `blocks init` only scaffolds `blocks/data/schemas/`, `blocks/data/rules.json`, and `.env.example` — it has no release-related output at all. `deploy` and `builds list` both resolve which repo to act on directly from the project's linked assets (see below), not from any file on disk.
+
+## Safe read commands
+
+- **`blocks release status <buildId> [--json]`** — one build's status by id (positional arg, or `--build-id <id>`).
+- **`blocks release builds get <buildId> [--json]`** — literally the same call as `release status`; it's a pure alias in the CLI's own source (`releaseBuildsGet` just calls `releaseStatus(argv)`), not a different endpoint or response shape. Use whichever name the user said.
+- **`blocks release builds list [<repoId>] [--repo-id <repoId>] [--json]`** — all builds for one repository. `repoId` is optional: if omitted, the CLI auto-resolves it from the selected project's linked repo assets the same way `deploy` does (see "Resolving the repo" below) — **except** when more than one repo is linked, in which case it falls back to an interactive `selectFromList()` prompt instead of erring or guessing. That prompt has no stdin in a non-interactive/agent run and will hang — if you can't guarantee a human is watching the terminal, resolve and pass `--repo-id` explicitly instead of letting this fall through to the prompt (the same hang risk applies to `blocks new web`'s OIDC-client picker when `--client-id` is omitted — always resolve and pass required values explicitly rather than relying on an interactive fallback).
+
+None of these mutate anything — safe to run without confirmation.
+
+## Mutating: trigger a deploy
+
+```bash
+blocks release deploy --dry-run --json   # show the exact request first
+blocks release deploy --yes --json       # only after the user approves
+```
+
+There is **no `--repo-id` flag on `deploy`** — the repo is always resolved automatically (see below); passing `--repo-id` is not recognized by this command.
+
+### Resolving the repo
+
+`deploy` never takes a repo id as input. It resolves one from the currently selected project's linked assets:
+
+1. It looks up the project's linked repo resources for the project's `tenantGroupId`.
+2. If exactly one repo is linked, that's the one used.
+3. If multiple are linked, it picks the one whose asset `name` matches the project's `environment` (case-insensitive); if none matches, it throws `repo_ambiguous`.
+4. If none are linked at all, it throws `repo_not_linked`.
+
+### Branch/environment safety check
+
+Before building, `deploy` fetches the resolved repo's details to read its linked branch, then compares that branch to the project's `environment` (case-insensitive). If they don't match, it throws `branch_environment_mismatch` rather than building the wrong branch.
+
+### Error codes you may see
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `repo_not_linked` | No repo is linked to this project at all. | Link a repo from the Blocks portal (requires GitHub OAuth), then re-run. |
+| `repo_ambiguous` | Multiple repos are linked and none is named for the project's `environment`. | Check the repo links for this project from the Blocks portal. |
+| `repo_not_found` | The linked asset's repo id wasn't found in blocks-release when fetching repo details. | Check the repo link for this project from the Blocks portal. |
+| `branch_environment_mismatch` | The linked repo's branch doesn't match the project's `environment` (e.g. repo is on `main` but environment is `staging`). Message states the branch found and the environment required. | Point the linked repo at a branch named for the environment, or relink the correct branch from the Blocks portal. |
+| `build_wait_timeout` | Only with `--wait`: no terminal build status was seen before `--timeout` elapsed. | Check manually with `blocks release status <buildId>`. |
+
+### Optional flags
+
+- **`--domain <domain>`** — before triggering the build, makes an extra call to set a custom deployment domain for this repo/environment.
+- **`--wait`** — after triggering, polls the build status (by the returned `buildId`) every `--poll-interval` seconds until the status matches a terminal pattern (succeeded/success/completed/failed/error/cancelled/aborted/done, case-insensitive) or `--timeout` elapses (then throws `build_wait_timeout`).
+- **`--poll-interval <seconds>`** — polling interval for `--wait`, default `10`.
+- **`--timeout <seconds>`** — max time to wait for `--wait`, default `900`.
+
+`--dry-run` prints the resolved `repoId`, `branch`, `environment`, `projectKey`, and (if given) `domain` — it does **not** build a request body from any local file, since none exists. The real request when not a dry run is simply `{ repoId }`. Always show the `--dry-run` output and get explicit approval before re-running with `--yes` — never skip straight to `--yes`.
+
+## Gotchas
+
+- **No SDK path, ever.** If asked "how do I trigger a deploy from my app," the answer is: you don't — this is a CLI-only, human/CI-operated action, not something to wire into frontend code.
+- **No artifact upload.** `release deploy` triggers a *configured* pipeline/repository build — it does not accept or upload a build artifact you hand it. If a user asks to "upload my build and deploy it," that capability doesn't exist in this CLI; say so rather than inventing an upload flag.
+- **`release builds get` and `release status` are the same command.** Don't treat them as returning different data or document them separately — the CLI's own source has `builds get` call `release status` directly.
+- **Release commands are project-scoped, not account-level.** `deploy`, `status`, and `builds list` all run on an impersonated project token, and `deploy`/`builds list` both resolve which project's linked assets to use from whichever project is currently selected via `blocks use`. Behavior changes if the selected project changes; there is no account-level/project-independent mode here.
+- **`deploy` never takes a repo id from the user** — it's always auto-resolved from the project's linked assets, with a real branch/environment safety check before it will build. Don't offer or accept a `--repo-id` flag on `deploy`.
+- **`builds list --repo-id` is optional, not required** — it falls back to the same auto-resolve logic as `deploy`, but that fallback can hit an interactive prompt if multiple repos are linked. Pass `--repo-id` explicitly in any non-interactive/agent context to avoid the hang.
+- **`buildId` for `status`/`builds get` is always required**, never guessed — ask the user rather than assuming a value.
+- **`--dry-run` before `--yes`, always** — same discipline as every other mutating `blocks` command in this pack.
+
+## Example trigger prompts
+
+- "Deploy this project's configured release."
+- "Trigger a build for the linked repo."
+- "Check the status of build `<buildId>`."
+- "Did my last deploy finish? Look up build `<buildId>`."
+- "List the recent builds for this repo."
+- "Deploy and wait until it finishes." → add `--wait` (optionally `--poll-interval`/`--timeout`).
+- "Deploy this to a custom domain." → add `--domain <domain>`.
+- "Can you upload my compiled artifact and deploy it?" → not supported; explain there's no artifact-upload path, only triggering the repo's configured pipeline.

package/dist/skills/blocks-secrets/SKILL.md

@@ -1,81 +1,81 @@
----
-name: blocks-secrets
-description: "Save and retrieve arbitrary named secret values (e.g. captcha provider config, third-party API keys) for a SELISE Blocks project via the blocks CLI's `secrets get`/`secrets save` commands, project-scoped with an impersonated project token. CLI-only surface, no SDK equivalent by design. Storage is generic key/value — shape depends entirely on the secret key, not fixed per type. Use for saving/rotating a secret's key-value pairs or reading one back. `get`'s response is the raw, unredacted value — treat CLI output as sensitive."
----
-
-# Blocks Secrets
-
-This skill manages **generic tenant secret storage** — arbitrary named secret values scoped to a project, via the `blocks secrets *` CLI. It is not tied to any one feature: a project can store a `captcha` secret, an `smtp` secret, or anything else under whatever `secretKey` name it chooses. The shape of the stored value is a flat, caller-defined JSON object (`--key-value-pairs`) — there is no fixed schema across secrets.
-
-**CLI-only, no SDK path, by explicit design.** There is no `@seliseblocks/client` method anywhere for reading or writing tenant secrets (the SDK's only "secret" surfaces are unrelated: MFA enrollment secrets and OIDC `clientSecret`). If a user wants to store or fetch a project secret, `blocks secrets get`/`blocks secrets save` is the only path — don't suggest an SDK call for this.
-
-**Prerequisite:** a project is selected (`blocks use <tenantId>`). If login/project state is unknown, run the blocks-onboarding skill first.
-
-## Command family
-
-Both commands require an **impersonated project token** — there is no account-token path, consistent with `storage config *` and other project-scoped admin surfaces.
-
-| Command | What it does |
-|---|---|
-| `blocks secrets get <secretKey>` | `<secretKey>` positional, or `--secret-key` (required if no positional). Also takes `--page-number` (default `0`) / `--page-size` (default `10`). Read-only. Response is untyped and printed as-is — **not redacted** (see Gotchas). |
-| `blocks secrets save` | Upsert — create or update. Mutating; standard `--dry-run`/`--yes` discipline applies. |
-
-```bash
-blocks secrets get captcha --json
-blocks secrets get --secret-key captcha --page-size 25 --json
-```
-
-The `secretKey` positional argument wins over `--secret-key` if both are somehow given; only one is required. The paging flags imply the response can be a paged list of items filed under that `secretKey`, not necessarily a single flat value — confirm actual shape from what the call returns rather than assuming a single-object response.
-
-## `secrets save` — fields
-
-`save` builds its request body from `--body`/`--file` (a raw JSON object, applied first) merged with these convenience flags (applied second, so they win if both are given):
-
-| Flag | Body field |
-|---|---|
-| `--secret-key` | `secretKey` |
-| `--item-id` | `itemId` |
-| `--key-value-pairs` | `keyValuePairs` |
-
-`--key-value-pairs` takes a JSON **object** string (e.g. `'{"isEnable":"true"}'`) — the CLI rejects arrays or non-objects with `--key-value-pairs must be a JSON object`. Unset convenience flags are dropped, so they never overwrite a field already present in `--body`/`--file`.
-
-```bash
-blocks secrets save --secret-key captcha \
-  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
-  --dry-run --json
-
-blocks secrets save --secret-key captcha \
-  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
-  --yes --json
-
-# Update an existing secret record
-blocks secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json
-```
-
-`save` is create-or-update in one command: omit `--item-id` to create, pass it to update. The captcha example above is only an illustration — `--key-value-pairs` accepts whatever fields the caller's `secretKey` namespace needs.
-
-## `--dry-run` before `--yes` — always
-
-`save` follows the standard `blocks` mutation discipline: passing neither `--dry-run` nor `--yes` drops into an interactive "Type 'yes' to continue" prompt, which is not viable in a scripted/agent context — always pass one explicitly.
-
-- `--dry-run` short-circuits **before** the confirmation prompt and **before any network call**: it prints the resolved request, with a redacted body, and returns.
-- `--yes` skips the interactive prompt and sends the real request.
-
-The dry-run preview's redaction is narrow: it walks `keyValuePairs` only, and replaces the *value* of any entry whose *key* matches a secret-shaped pattern (case-insensitive, e.g. ends in "key," or contains "secret"/"password") with `"***"`. It does **not** touch `secretKey`/`itemId` at the top level, and does **not** touch anything injected via `--body`/`--file` outside `keyValuePairs`. This redaction is preview-only — it never changes what is actually sent when `--yes` is used, and it has no effect on `secrets get`'s response or on the live response from `save` itself.
-
-## Gotchas (secret-handling — read before running either command)
-
-- **`get`'s response is raw and completely unredacted.** The command applies zero masking — the result is passed straight through and printed verbatim. There is no masked/redacted variant of this command. Whatever is stored under that `secretKey` comes back in full, as-is. Treat the output as sensitive: don't repeat the value back to the user beyond what they explicitly asked for, don't paste it into chat/logs/tickets, and never write it into a file that could get committed.
-- **`save`'s live response is also unredacted.** The dry-run preview masks secret-shaped `keyValuePairs` keys, but that's a preview-only convenience. The actual request always sends plaintext values, and whatever comes back is written unredacted too — if the API echoes the saved value back, handle that response with the same care as `get`'s.
-- **This is generic storage, not a captcha-specific feature.** `--key-value-pairs` is a flat JSON object whose fields are entirely defined by whoever picked the `secretKey` — there's no schema registry. Don't assume `isEnable`/`provider`/`captchaKey`/`captchaSecret` apply to a secret that isn't actually a captcha config.
-- **Impersonated project token only, no account-token path.** Both commands require a selected project (`blocks use <tenantId>`) first — same pattern as `storage config *`.
-- **No SDK equivalent exists.** Don't reach for `@seliseblocks/client` for this; the CLI is the only surface, by design.
-- **`save` is upsert, not two verbs.** Whether a call creates or updates is decided by the presence of `--item-id`, not by a different command name.
-
-## Example trigger prompts
-
-- "Save our reCAPTCHA settings as a project secret." → `secrets save --secret-key captcha --key-value-pairs '{...}' --dry-run --json`, confirm, then re-run with `--yes`.
-- "What's stored under the `captcha` secret?" → `secrets get captcha --json` — tell the user the raw stored value will be printed, and don't restate it beyond what they asked for.
-- "Rotate the captcha secret key." → `secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json` (update path — need the existing `itemId`, typically from a prior `secrets get`).
-- "Is there a way to list every secret in the project?" → there's no list-all; `secrets get` requires a `secretKey` and pages within it (`--page-number`/`--page-size`), it doesn't enumerate unknown keys.
-- "Can I read this from my frontend app with the SDK?" → no — `blocks secrets *` is CLI/admin-only; don't scaffold an SDK call, and never put a secret value into frontend code or a committed `.env` file.
+---
+name: blocks-secrets
+description: "Save and retrieve arbitrary named secret values (e.g. captcha provider config, third-party API keys) for a SELISE Blocks project via the blocks CLI's `secrets get`/`secrets save` commands, project-scoped with an impersonated project token. CLI-only surface, no SDK equivalent by design. Storage is generic key/value — shape depends entirely on the secret key, not fixed per type. Use for saving/rotating a secret's key-value pairs or reading one back. `get`'s response is the raw, unredacted value — treat CLI output as sensitive."
+---
+
+# Blocks Secrets
+
+This skill manages **generic tenant secret storage** — arbitrary named secret values scoped to a project, via the `blocks secrets *` CLI. It is not tied to any one feature: a project can store a `captcha` secret, an `smtp` secret, or anything else under whatever `secretKey` name it chooses. The shape of the stored value is a flat, caller-defined JSON object (`--key-value-pairs`) — there is no fixed schema across secrets.
+
+**CLI-only, no SDK path, by explicit design.** There is no `@seliseblocks/client` method anywhere for reading or writing tenant secrets (the SDK's only "secret" surfaces are unrelated: MFA enrollment secrets and OIDC `clientSecret`). If a user wants to store or fetch a project secret, `blocks secrets get`/`blocks secrets save` is the only path — don't suggest an SDK call for this.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`). If login/project state is unknown, run the blocks-onboarding skill first.
+
+## Command family
+
+Both commands require an **impersonated project token** — there is no account-token path, consistent with `storage config *` and other project-scoped admin surfaces.
+
+| Command | What it does |
+|---|---|
+| `blocks secrets get <secretKey>` | `<secretKey>` positional, or `--secret-key` (required if no positional). Also takes `--page-number` (default `0`) / `--page-size` (default `10`). Read-only. Response is untyped and printed as-is — **not redacted** (see Gotchas). |
+| `blocks secrets save` | Upsert — create or update. Mutating; standard `--dry-run`/`--yes` discipline applies. |
+
+```bash
+blocks secrets get captcha --json
+blocks secrets get --secret-key captcha --page-size 25 --json
+```
+
+The `secretKey` positional argument wins over `--secret-key` if both are somehow given; only one is required. The paging flags imply the response can be a paged list of items filed under that `secretKey`, not necessarily a single flat value — confirm actual shape from what the call returns rather than assuming a single-object response.
+
+## `secrets save` — fields
+
+`save` builds its request body from `--body`/`--file` (a raw JSON object, applied first) merged with these convenience flags (applied second, so they win if both are given):
+
+| Flag | Body field |
+|---|---|
+| `--secret-key` | `secretKey` |
+| `--item-id` | `itemId` |
+| `--key-value-pairs` | `keyValuePairs` |
+
+`--key-value-pairs` takes a JSON **object** string (e.g. `'{"isEnable":"true"}'`) — the CLI rejects arrays or non-objects with `--key-value-pairs must be a JSON object`. Unset convenience flags are dropped, so they never overwrite a field already present in `--body`/`--file`.
+
+```bash
+blocks secrets save --secret-key captcha \
+  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
+  --dry-run --json
+
+blocks secrets save --secret-key captcha \
+  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
+  --yes --json
+
+# Update an existing secret record
+blocks secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json
+```
+
+`save` is create-or-update in one command: omit `--item-id` to create, pass it to update. The captcha example above is only an illustration — `--key-value-pairs` accepts whatever fields the caller's `secretKey` namespace needs.
+
+## `--dry-run` before `--yes` — always
+
+`save` follows the standard `blocks` mutation discipline: passing neither `--dry-run` nor `--yes` drops into an interactive "Type 'yes' to continue" prompt, which is not viable in a scripted/agent context — always pass one explicitly.
+
+- `--dry-run` short-circuits **before** the confirmation prompt and **before any network call**: it prints the resolved request, with a redacted body, and returns.
+- `--yes` skips the interactive prompt and sends the real request.
+
+The dry-run preview's redaction is narrow: it walks `keyValuePairs` only, and replaces the *value* of any entry whose *key* matches a secret-shaped pattern (case-insensitive, e.g. ends in "key," or contains "secret"/"password") with `"***"`. It does **not** touch `secretKey`/`itemId` at the top level, and does **not** touch anything injected via `--body`/`--file` outside `keyValuePairs`. This redaction is preview-only — it never changes what is actually sent when `--yes` is used, and it has no effect on `secrets get`'s response or on the live response from `save` itself.
+
+## Gotchas (secret-handling — read before running either command)
+
+- **`get`'s response is raw and completely unredacted.** The command applies zero masking — the result is passed straight through and printed verbatim. There is no masked/redacted variant of this command. Whatever is stored under that `secretKey` comes back in full, as-is. Treat the output as sensitive: don't repeat the value back to the user beyond what they explicitly asked for, don't paste it into chat/logs/tickets, and never write it into a file that could get committed.
+- **`save`'s live response is also unredacted.** The dry-run preview masks secret-shaped `keyValuePairs` keys, but that's a preview-only convenience. The actual request always sends plaintext values, and whatever comes back is written unredacted too — if the API echoes the saved value back, handle that response with the same care as `get`'s.
+- **This is generic storage, not a captcha-specific feature.** `--key-value-pairs` is a flat JSON object whose fields are entirely defined by whoever picked the `secretKey` — there's no schema registry. Don't assume `isEnable`/`provider`/`captchaKey`/`captchaSecret` apply to a secret that isn't actually a captcha config.
+- **Impersonated project token only, no account-token path.** Both commands require a selected project (`blocks use <tenantId>`) first — same pattern as `storage config *`.
+- **No SDK equivalent exists.** Don't reach for `@seliseblocks/client` for this; the CLI is the only surface, by design.
+- **`save` is upsert, not two verbs.** Whether a call creates or updates is decided by the presence of `--item-id`, not by a different command name.
+
+## Example trigger prompts
+
+- "Save our reCAPTCHA settings as a project secret." → `secrets save --secret-key captcha --key-value-pairs '{...}' --dry-run --json`, confirm, then re-run with `--yes`.
+- "What's stored under the `captcha` secret?" → `secrets get captcha --json` — tell the user the raw stored value will be printed, and don't restate it beyond what they asked for.
+- "Rotate the captcha secret key." → `secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json` (update path — need the existing `itemId`, typically from a prior `secrets get`).
+- "Is there a way to list every secret in the project?" → there's no list-all; `secrets get` requires a `secretKey` and pages within it (`--page-number`/`--page-size`), it doesn't enumerate unknown keys.
+- "Can I read this from my frontend app with the SDK?" → no — `blocks secrets *` is CLI/admin-only; don't scaffold an SDK call, and never put a secret value into frontend code or a committed `.env` file.