@screenshotscout/cli 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ You need:
 
 - Node.js 22 or newer;
 - a Screenshot Scout [access key](https://screenshotscout.com/app/api-keys); and
-- the matching secret key only when you want automatic signing or the API key requires signed requests.
+- the matching secret key only when you want signed capture URLs or the API key requires signed requests.
 
 ## Install
 
@@ -55,7 +55,7 @@ $env:SCREENSHOTSCOUT_ACCESS_KEY = "YOUR_ACCESS_KEY"
 $env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY"
 ```
 
-`SCREENSHOTSCOUT_ACCESS_KEY` is required. `SCREENSHOTSCOUT_SECRET_KEY` is optional; omit its assignment for unsigned requests. When the secret key is configured, capture requests and generated capture URLs are signed automatically, while the secret key stays local.
+`SCREENSHOTSCOUT_ACCESS_KEY` is required. `SCREENSHOTSCOUT_SECRET_KEY` is optional; omit its assignment for unsigned requests. When the secret key is configured, generated capture URLs and captures sent with `--method get` are signed automatically, while the secret key stays local.
 
 ## Commands
 
@@ -77,7 +77,7 @@ screenshotscout capture "https://example.com" \
   --output screenshot.webp
 ```
 
-`capture` accepts `--method get` or `--method post`. You can omit `--method` unless you need to select one explicitly.
+`capture` accepts `--method get` or `--method post`. You can omit `--method` unless you need to select one explicitly, such as `--method get` for signed requests.
 
 ```sh
 screenshotscout capture "https://example.com" --method post --format webp --output screenshot.webp
@@ -225,7 +225,7 @@ More inline-flag, options-file, POSIX shell, PowerShell, and CI examples are in
 
 - Run `screenshotscout --help` or `screenshotscout <command> --help` to check command syntax and current capture-option value shapes.
 - If the CLI reports that an access key is required, set `SCREENSHOTSCOUT_ACCESS_KEY` in the same process environment that runs the command.
-- If the API reports `signature_required`, set the matching `SCREENSHOTSCOUT_SECRET_KEY`; the CLI will sign the request automatically. See [Signed requests](https://screenshotscout.com/docs/signed-requests).
+- If the API reports `signature_required`, set the matching `SCREENSHOTSCOUT_SECRET_KEY` and add `--method get`. See [Signed requests](https://screenshotscout.com/docs/signed-requests).
 - If an option is rejected with exit status `2`, check whether it uses CLI `kebab-case`, whether a boolean uses bare or inline syntax, and whether a singleton flag was repeated.
 - If an options file is rejected, confirm that it is a JSON object using exact API `snake_case` names and JSON value types.
 - If a file write fails, confirm that its parent directory exists and is writable.

package/dist/capture.js

@@ -1,11 +1,20 @@
+import { CliUsageError } from "./cli-usage-error.js";
 import { parseCaptureCommandInput } from "./input.js";
 import { writeCaptureResult } from "./result.js";
-import { captureWithScreenshotScoutClient, createScreenshotScoutClient, } from "./sdk.js";
+import { captureWithScreenshotScoutClient, createScreenshotScoutClient, isSecretKeyConfigured, } from "./sdk.js";
+const SIGNED_POST_MESSAGE = "SCREENSHOTSCOUT_SECRET_KEY is set, and POST requests can't be signed. Add --method get, or unset SCREENSHOTSCOUT_SECRET_KEY to send an unsigned POST request.";
 /** Run one capture command as a direct input -> SDK -> result adapter. */
 export async function runCaptureCommand(args, dependencies = {}) {
     const input = dependencies.inputReader === undefined
         ? await parseCaptureCommandInput(args)
         : await parseCaptureCommandInput(args, dependencies.inputReader);
+    const secretKeyConfigured = dependencies.client === undefined
+        ? isSecretKeyConfigured()
+        : dependencies.secretKeyConfigured === true;
+    // Only GET requests can be signed, and an omitted --method means POST
+    if (secretKeyConfigured && input.method !== "get") {
+        throw new CliUsageError(SIGNED_POST_MESSAGE);
+    }
     const client = dependencies.client ?? createScreenshotScoutClient();
     const response = await captureWithScreenshotScoutClient(client, input.targetUrl, input.captureOptions, input.method);
     if (dependencies.resultIo === undefined) {

package/dist/help.js

@@ -26,7 +26,7 @@ export function captureCommandHelp() {
 
 CLI controls:
   --options <path|->       Read a snake_case JSON options object from a file or standard input.
-  --method <get|post>      Select the SDK capture request method.
+  --method <get|post>      Select the request method (default post). Signed captures need get.
   -o, --output <path|->    Write the response to a file or standard output.
   --help                   Show this help.
 

package/dist/sdk.js

@@ -11,6 +11,10 @@ export function createScreenshotScoutClient(environment = process.env, clientFac
     };
     return clientFactory(options);
 }
+/** Whether the environment gives the client a secret key, as createScreenshotScoutClient passes it. */
+export function isSecretKeyConfigured(environment = process.env) {
+    return environment.SCREENSHOTSCOUT_SECRET_KEY !== undefined;
+}
 /** Make one capture call with only an explicitly selected request method. */
 export function captureWithScreenshotScoutClient(client, targetUrl, captureOptions, method) {
     if (method === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@screenshotscout/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official command-line interface for the Screenshot Scout screenshot API.",
   "type": "module",
   "bin": {
@@ -49,7 +49,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@screenshotscout/sdk": "0.3.0"
+    "@screenshotscout/sdk": "0.4.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",