requestshield 0.1.4 → 0.1.5

package/skills/requestshield/references/cli.md

@@ -1,182 +1,183 @@
-# `requestshield` CLI reference
-
-Every RequestShield platform action goes through this CLI. There is no supported way
-to create keys, read the contract, or check traffic by hand-crafting HTTP calls, so if
-a task needs one of these values, run the command rather than guessing.
-
-Commands marked **auth** require a signed-in session (`requestshield signin`). The CLI
-also exposes local commands that do not need platform API access, such as `--help`,
-`--version`, and agent setup. Check once with `auth status` before a multi-step
-platform task instead of discovering it halfway through an edit.
-
-Most commands print JSON shaped `{"ok": true, "data": {...}}`. Parse `data`; treat
-`ok: false` as a hard stop and surface the message rather than continuing with edits.
-
-## Contents
-
-- [General](#general)
-- [Authentication](#authentication)
-- [Key management](#key-management)
-- [Integration contract](#integration-contract)
-- [Applications](#applications)
-- [Credentials](#credentials)
-- [Service and monitoring](#service-and-monitoring)
-- [Billing](#billing)
-- [Agent integration](#agent-integration)
-
-## General
-
-| Command | Purpose |
-| --- | --- |
-| `requestshield --help` | Usage and the full command list. Run this if a command below is rejected — the installed CLI may be older or newer than this file. |
-| `requestshield --version` | Installed CLI version, e.g. `requestshield 1.0.0`. |
-| `requestshield update check` | Latest available version. Use it when behaviour disagrees with this reference. |
-
-## Authentication
-
-```bash
-requestshield signin
-requestshield auth status
-```
-
-**auth/API.**
-
-`signin` is interactive and stores a session on the machine. **Never try to automate
-it or ask for the user's credentials** — if the user is signed out, tell them to run it
-themselves and wait.
-
-`auth status` returns `{"ok":true,"data":{"authenticated":true,"customer_id":"customer_456"}}`.
-The `customer_id` is useful context to echo back so the user can confirm they are
-operating on the right account before you create or deactivate anything.
-
-## Key management
-
-**The user runs these, not you.** They print the API Secret or change state for a live
-App Key, so hand over the exact command and let them run it in their own terminal. See
-"Key and secret management" in `SKILL.md` for the hand-off and the follow-up
-presence check.
-
-```bash
-requestshield keys create --app-name <name>
-requestshield keys deactive --app-key <app-key>      # or --app-name <name>
-requestshield app key rotate --app-key <app-key>     # or --app-name <name>
-```
-
-`keys create` returns both halves:
-
-```
-App Key: app_123
-Secret Key: rs_sk_xxxxx
-Save this Secret Key now. It will not be shown again.
-```
-
-The Secret Key appears exactly once. Warn the user *before* they run the command that
-they need somewhere to put it, and afterwards point them at the environment variable
-rather than repeating the value. Never ask them to paste the secret back — confirm it
-only by presence. See the secret-handling rules in `SKILL.md`.
-
-`keys deactive` (spelled that way in the CLI) needs at least one of `--app-key` or
-`--app-name`; if both are given, `--app-key` wins. Deactivation stops traffic being
-verified for that key, so name the affected app explicitly when you hand the command
-over and make sure the user means that key.
-
-`app key rotate` issues a new Secret Key for an existing App Key and deactivates the
-previous one. This is the correct response to a leaked or lost secret — it keeps the
-App Key stable, so no browser or config change is needed beyond the new secret. Like
-`keys create`, the user runs it.
-
-## Integration contract
-
-```bash
-requestshield contract
-```
-
-**auth.** The authoritative integration surface — run this before writing any
-integration code. The block below is an **illustration of the shape only**; never read
-values out of it, and in particular do not treat its `available_modes` as the modes your
-customer has:
-
-```json
-{"ok":true,"data":{
-  "contract_version":"2026-08-27",
-  "browser":{"script_url":"https://.../intellifend.js","token_header":"X-IntelliFend-Token",
-             "available_modes":["manual"]},
-  "backend":{"supported_languages":["java"],"min_jdk":17},
-  "release_state":"..."}}
-```
-
-Use `script_url` and `token_header` verbatim. Check `available_modes` before committing
-to seamless or manual — a mode absent from that list is not released, and writing an
-integration against it produces code that will not work. Check `supported_languages`
-before promising a backend integration for a stack that is not listed; the browser side
-alone provides no protection, so an unsupported backend means the honest answer is
-"not yet supported here".
-
-## Applications
-
-```bash
-requestshield apps list
-requestshield apps get <app-key>
-```
-
-**auth.** `apps list` returns the applications the current user can access, each with
-`app_key`, `name`, and `status`. Use it to resolve a human-supplied app name to a key
-rather than asking the user to retype one.
-
-`apps get <app-key>` returns `app_id`, `app_name`, and `status`. Status distinguishes a
-key that has never seen traffic (`ready`) from one in normal service (`active`) — which
-is exactly the difference between "the integration is not wired up yet" and "it is
-working", so check it before spending time debugging code.
-
-## Credentials
-
-```bash
-requestshield credentials status <app-key>
-```
-
-**auth.** Returns metadata only — `provisioned`, `active`, `shared` — and never the
-secret value. Use it to answer "is the secret configured?" without anyone having to
-paste a credential. A key that is `provisioned: false` explains backend failures far
-faster than reading code.
-
-## Service and monitoring
-
-```bash
-requestshield server
-requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
-```
-
-**auth.** `server` reports `healthy` or `degraded`. Check it first when an integration
-that was working starts behaving oddly — a degraded platform explains fail-open
-behaviour on the backend without anything being wrong in the customer's code.
-
-`challenge volume` is runtime evidence that the browser/platform half is active. It is
-not proof that the protected backend enforces a blocking decision; the controlled
-negative test in `SKILL.md` provides that evidence. Times are ISO-8601
-(`2026-08-01T00:00:00Z`); `--granularity` takes values such as `hour` or `day`. A
-`challenge_count` of zero after the user has exercised the endpoint means the browser
-half is not firing — that is a browser-side bug, not a backend one, so start with the
-mode's reference file.
-
-## Billing
-
-```bash
-requestshield get billing
-```
-
-**auth.** Current plan and usage for the application. Read-only; surface it when the
-user asks about cost or limits.
-
-## Agent integration
-
-```bash
-requestshield agent setup
-requestshield agent setup --agent claude
-requestshield agent setup --agent codex
-```
-
-Local setup. Installs this skill for the named agent. With no `--agent`, the CLI detects
-which agent is in use. Run it when the user wants the skill available in another repo or
-for the other agent; it is the supported alternative to copying files by hand. It should
-not require a RequestShield App Key or API Secret, and it must not create, rotate, or
-deactivate customer credentials.
+# `requestshield` CLI reference
+
+Every RequestShield platform action goes through this CLI. There is no supported way
+to create keys, read the contract, or check traffic by hand-crafting HTTP calls, so if
+a task needs one of these values, run the command rather than guessing.
+
+Commands marked **auth** require a signed-in session (`requestshield signin`). The CLI
+also exposes local commands that do not need platform API access, such as `--help`,
+`--version`, and agent setup. Check once with `auth status` before a multi-step
+platform task instead of discovering it halfway through an edit.
+
+Most commands print JSON shaped `{"ok": true, "data": {...}}`. Parse `data`; treat
+`ok: false` as a hard stop and surface the message rather than continuing with edits.
+
+## Contents
+
+- [General](#general)
+- [Authentication](#authentication)
+- [Key management](#key-management)
+- [Integration contract](#integration-contract)
+- [Applications](#applications)
+- [Credentials](#credentials)
+- [Service and monitoring](#service-and-monitoring)
+- [Billing](#billing)
+- [Agent integration](#agent-integration)
+
+## General
+
+| Command | Purpose |
+| --- | --- |
+| `requestshield --help` | Usage and the full command list. Run this if a command below is rejected — the installed CLI may be older or newer than this file. |
+| `requestshield --version` | Installed CLI version, e.g. `requestshield 1.0.0`. |
+| `requestshield update check` | Latest available version. Use it when behaviour disagrees with this reference. |
+
+## Authentication
+
+```bash
+requestshield signin
+requestshield auth status
+```
+
+**auth/API.**
+
+`signin` is interactive and stores a session on the machine. **Never try to automate
+it or ask for the user's credentials** — if the user is signed out, tell them to run it
+themselves and wait.
+
+`auth status` returns `{"ok":true,"data":{"authenticated":true,"customer_id":"customer_456"}}`.
+The `customer_id` is useful context to echo back so the user can confirm they are
+operating on the right account before you create or deactivate anything.
+
+## Key management
+
+**The user runs these, not you.** They print the API Secret or change state for a live
+App Key, so hand over the exact command and let them run it in their own terminal. See
+"Key and secret management" in `SKILL.md` for the hand-off and the follow-up
+presence check.
+
+```bash
+requestshield keys create --app-name <name>
+requestshield keys deactive --app-key <app-key>      # or --app-name <name>
+requestshield app key rotate --app-key <app-key>     # or --app-name <name>
+```
+
+`keys create` returns both halves:
+
+```
+App Key: app_123
+Secret Key: rs_sk_xxxxx
+Save this Secret Key now. It will not be shown again.
+```
+
+The Secret Key appears exactly once. Warn the user *before* they run the command that
+they need somewhere to put it, and afterwards point them at the environment variable
+rather than repeating the value. Never ask them to paste the secret back — confirm it
+only by presence. See the secret-handling rules in `SKILL.md`.
+
+`keys deactive` (spelled that way in the CLI) needs at least one of `--app-key` or
+`--app-name`; if both are given, `--app-key` wins. Deactivation stops traffic being
+verified for that key, so name the affected app explicitly when you hand the command
+over and make sure the user means that key.
+
+`app key rotate` issues a new Secret Key for an existing App Key and deactivates the
+previous one. This is the correct response to a leaked or lost secret — it keeps the
+App Key stable, so no browser or config change is needed beyond the new secret. Like
+`keys create`, the user runs it.
+
+## Integration contract
+
+```bash
+requestshield contract
+```
+
+**auth.** The authoritative integration surface — run this before writing any
+integration code. The block below is an **illustration of the shape only**; never read
+values out of it, and in particular do not treat its `available_modes` as the modes your
+customer has:
+
+```json
+{"ok":true,"data":{
+  "contract_version":"2026-08-27",
+  "browser":{"script_url":"https://.../intellifend.js","token_header":"X-IntelliFend-Token",
+             "available_modes":["manual"]},
+  "backend":{"supported_languages":["java"],"min_jdk":17},
+  "release_state":"..."}}
+```
+
+Use `script_url` and `token_header` verbatim. Check `available_modes` before committing
+to seamless or manual — a mode absent from that list is not released, and writing an
+integration against it produces code that will not work. Check `supported_languages`
+before promising a backend integration for a stack that is not listed; the browser side
+alone provides no protection, so an unsupported backend means the honest answer is
+"not yet supported here".
+
+## Applications
+
+```bash
+requestshield apps list
+requestshield apps get <app-key>
+```
+
+**auth.** `apps list` returns the applications the current user can access, each with
+`appKey`, `name`, `status`, `createdAt`, and `updatedAt`; JSON output also includes
+`nextCursor`. Use it to resolve a human-supplied app name to a key rather than asking
+the user to retype one.
+
+`apps get <app-key>` returns `app_key`, `name`, and `status`. Status distinguishes a
+key that has never seen traffic (`ready`) from one in normal service (`active`) — which
+is exactly the difference between "the integration is not wired up yet" and "it is
+working", so check it before spending time debugging code.
+
+## Credentials
+
+```bash
+requestshield credentials status <app-key>
+```
+
+**auth.** Returns metadata only — `provisioned`, `active`, `shared` — and never the
+secret value. Use it to answer "is the secret configured?" without anyone having to
+paste a credential. A key that is `provisioned: false` explains backend failures far
+faster than reading code.
+
+## Service and monitoring
+
+```bash
+requestshield server
+requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
+```
+
+**auth.** `server` reports `healthy` or `degraded`. Check it first when an integration
+that was working starts behaving oddly — a degraded platform explains fail-open
+behaviour on the backend without anything being wrong in the customer's code.
+
+`challenge volume` is runtime evidence that the browser/platform half is active. It is
+not proof that the protected backend enforces a blocking decision; the controlled
+negative test in `SKILL.md` provides that evidence. Times are ISO-8601
+(`2026-08-01T00:00:00Z`); `--granularity` takes values such as `hour` or `day`. A
+`challenge_count` of zero after the user has exercised the endpoint means the browser
+half is not firing — that is a browser-side bug, not a backend one, so start with the
+mode's reference file.
+
+## Billing
+
+```bash
+requestshield get billing <app-key>
+```
+
+**auth.** Current plan and usage for the explicitly selected application. Read-only;
+surface it when the user asks about cost or limits.
+
+## Agent integration
+
+```bash
+requestshield agent setup
+requestshield agent setup --agent claude
+requestshield agent setup --agent codex
+```
+
+Local setup. Installs this skill for the named agent. With no `--agent`, the CLI detects
+which agent is in use. Run it when the user wants the skill available in another repo or
+for the other agent; it is the supported alternative to copying files by hand. It should
+not require a RequestShield App Key or API Secret, and it must not create, rotate, or
+deactivate customer credentials.