docs: document --max-failures and cli.maxFailures [RED-1227]

cli/checkly-test.mdx

@@ -29,6 +29,7 @@ npx checkly test [arguments] [options]
 | `--grep, -g` | - | Only run checks where the check name matches a regular expression. Default: `.*` |
 | `--list` | - | List all checks but don't run them. |
 | `--location, -l` | - | The location to run the checks at. |
+| `--max-failures` | - | Stop waiting for the remaining checks once this many checks have failed, and exit with a failing status code. |
 | `--private-location` | - | The private location to run checks at. |
 | `--[no-]record` | - | Record test session results in Checkly with full logs, traces and videos. Records by default since CLI v8.0.0. |
 | `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
@@ -156,6 +157,34 @@ npx checkly test -l="eu-west-1"
 
 </ResponseField>
 
+<ResponseField name="--max-failures" type="number">
+
+Stop waiting for the remaining checks once this many checks have failed (a whole number of 1 or more), and exit with a failing status code. Use it in CI to see a broken change fail early instead of waiting for the whole run. Overrides `cli.maxFailures` in your Checkly config.
+
+Only a check's final result counts toward the limit: a check that passes after a retry does not count, and neither does a degraded check. If the failure that reaches the limit is the last check to finish, the run completes normally.
+
+When the limit is reached, the CLI writes its reports, marks the remaining checks as not finished, and asks Checkly to cancel the test session. Only some check types, such as Playwright Check Suites, can be cancelled once they are running, so other checks may still run to completion in Checkly. The `json` reporter gives those checks `"result": "Not finished"` and adds a top-level `"stoppedEarly": { "reason": "maxFailures", "maxFailures": <n> }` field.
+
+Cannot be combined with `--detach` or `--update-snapshots`.
+
+**Usage:**
+
+```bash Terminal
+npx checkly test --max-failures=1
+```
+
+**Examples:**
+
+```bash Terminal
+# Stop at the first failed check
+npx checkly test --max-failures=1
+
+# Retry failing checks, and stop once three checks still fail after their retries
+npx checkly test --retries=2 --max-failures=3
+```
+
+</ResponseField>
+
 <ResponseField name="--private-location" type="string">
 
 The private location to run checks at.

cli/checkly-trigger.mdx

@@ -28,6 +28,7 @@ npx checkly trigger [options]
 | `--env-file` | - | dotenv file path to be passed. For example `--env-file="./.env"` |
 | `--fail-on-no-matching` | - | Exit with a failing status code when there are no matching tests. |
 | `--location, -l` | - | The location to run the checks at. |
+| `--max-failures` | - | Stop waiting for the remaining checks once this many checks have failed, and exit with a failing status code. |
 | `--private-location` | - | The private location to run checks at. |
 | `--[no-]record` | - | Record test session results in Checkly with full logs, traces and videos. Records by default since CLI v8.0.0. |
 | `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
@@ -144,6 +145,34 @@ npx checkly trigger -l="us-east-1"
 Choose from available Checkly public locations like us-east-1, eu-west-1, ap-southeast-1, etc.
 </ResponseField>
 
+<ResponseField name="--max-failures" type="number">
+
+Stop waiting for the remaining checks once this many checks have failed (a whole number of 1 or more), and exit with a failing status code. Use it in CI to see a broken change fail early instead of waiting for the whole run. Overrides `cli.maxFailures` in your Checkly config.
+
+Only a check's final result counts toward the limit: a check that passes after a retry does not count, and neither does a degraded check. If the failure that reaches the limit is the last check to finish, the run completes normally.
+
+When the limit is reached, the CLI writes its reports, marks the remaining checks as not finished, and asks Checkly to cancel the test session. Only some check types, such as Playwright Check Suites, can be cancelled once they are running, so other checks may still run to completion in Checkly. The `json` reporter gives those checks `"result": "Not finished"` and adds a top-level `"stoppedEarly": { "reason": "maxFailures", "maxFailures": <n> }` field.
+
+Cannot be combined with `--detach`.
+
+**Usage:**
+
+```bash Terminal
+npx checkly trigger --max-failures=1
+```
+
+**Examples:**
+
+```bash Terminal
+# Stop at the first failed check
+npx checkly trigger --max-failures=1
+
+# Retry failing checks, and stop once three checks still fail after their retries
+npx checkly trigger --retries=2 --max-failures=3
+```
+
+</ResponseField>
+
 <ResponseField name="--private-location" type="string">
 
 The private location to run checks at.

constructs/project.mdx

@@ -151,6 +151,7 @@ export default defineConfig({
 | `runLocation` | `string` | ❌ | - | Default location for `checkly test` and `checkly trigger` |
 | `privateRunLocation` | `string` | ❌ | - | Default private location for CLI commands |
 | `retries` | `number` | ❌ | `0` | Default retry count for failing checks (max 3) |
+| `maxFailures` | `number` | ❌ | - | Stop `checkly test` and `checkly trigger` once this many checks have failed. The `--max-failures` flag overrides it. See [`checkly test`](/cli/checkly-test) |
 
 **Use cases**: Local testing defaults, CI/CD configuration, development workflow.
 </ResponseField>