--- title: 'CLI' description: 'Complete reference for the Yorker CLI — all commands, flags, and environment variables.' section: 'Reference' canonical_url: 'https://yorkermonitoring.com/docs/reference/cli' --- # CLI The Yorker CLI manages monitors, alerts, SLOs, notification channels, and private locations. Use it for infrastructure-as-code deployments from `yorker.config.yaml`, or manage resources imperatively with CRUD commands. --- ## Installation ```bash npm install -g @yorker/cli ``` Or locally in a project: ```bash npm install --save-dev @yorker/cli ``` --- ## Authentication For interactive use, run `yorker login`. The command opens a browser, mints an API key for your team, and stores it at `~/.yorker/credentials` (mode 0600). ```bash yorker login ``` For CI, Docker, and other headless contexts, set `YORKER_API_KEY` instead. Generate a key from **Settings > API Keys** in the dashboard: ```bash export YORKER_API_KEY=sk_your_key_here ``` The CLI resolves auth in this order on every invocation: 1. `--api-key` flag 2. `YORKER_API_KEY` environment variable 3. `~/.yorker/credentials` (written by `yorker login`) 4. Otherwise, the command exits with code `2` (authentication failure). The same precedence applies to the API URL via `--api-url`, `YORKER_API_URL`, the persisted file, then the default `https://yorkermonitoring.com`. --- ## Global Flags These flags are available on every command: | Flag | Description | |---|---| | `--json` | Output in structured JSON format. | | `--quiet` | Suppress non-essential output. | | `--no-color` | Disable colored output. | | `--verbose` | Enable verbose/debug output. | | `--api-url ` | Control plane URL (default: `https://yorkermonitoring.com`). Also settable via `YORKER_API_URL`. | | `--api-key ` | API key. Also settable via `YORKER_API_KEY`. | | `--help`, `-h` | Show help. | | `--version`, `-V` | Show version. | --- ## Environment Variables | Variable | Required | Default | Description | |---|---|---|---| | `YORKER_API_KEY` | Yes | — | API key for authentication. Keys start with `sk_`. | | `YORKER_API_URL` | No | `https://yorkermonitoring.com` | Control plane base URL. Override for self-hosted or development. | --- ## Exit Codes | Code | Meaning | |---|---| | `0` | Success. | | `1` | General error (validation failure, API error, missing config). | | `2` | Authentication failure (invalid or missing API key). | | `3` | Plan/quota limit exceeded. | | `4` | Partial failure (some operations succeeded, others failed). | | `5` | Drift detected — remote resources were modified outside the CLI. | | `10` | `yorker status` reports one or more unhealthy monitors. | --- ## Commands ### `yorker login` Authenticate the CLI by approving access in your browser. ```bash yorker login [--force] ``` Opens the consent page at `https://yorkermonitoring.com/cli/auth`, where you click **Authorize** to mint a real API key tied to your team. The key is named `CLI ` (so you can tell machines apart on the dashboard), gets posted back to a one-shot localhost listener, and is stored at `~/.yorker/credentials` with mode `0600`. You can see the key on the dashboard at **Settings > API Keys**, and revoke it from the same page or via `yorker logout --revoke`. If `~/.yorker/credentials` already exists, `yorker login` exits without re-authenticating. Pass `--force` to mint a new key and overwrite the file. | Flag | Description | |---|---| | `--force` | Re-authenticate and overwrite existing credentials. | The standard global flags `--api-url`, `--json`, and `--quiet` work here too. Use `--api-url` to authenticate against a non-default control plane (e.g. self-hosted or staging). #### Auth resolution order The CLI looks up auth in this order on every invocation, including immediately after `yorker login`: 1. `--api-key` flag 2. `YORKER_API_KEY` environment variable 3. `~/.yorker/credentials` 4. Otherwise, the command exits with code `2` (authentication failure). This means a `YORKER_API_KEY` set in your shell wins over a stored credential. If you want to switch teams temporarily, set the env var; to switch permanently, run `yorker logout` then `yorker login` again. #### Example output TTY success path: ``` Yorker login Opening: https://yorkermonitoring.com/cli/auth?port=51823&state=...&hostname=laptop If your browser doesn't open, paste the URL above. ✓ Logged in Saved credentials to /Users/you/.yorker/credentials Next steps: 1. yorker init scaffold a yorker.config.yaml 2. yorker deploy push monitors to https://yorkermonitoring.com ``` #### `--json` output ```json { "ok": true, "data": { "apiUrl": "https://yorkermonitoring.com", "credentialsPath": "/Users/you/.yorker/credentials", "createdAt": "2026-05-08T14:23:00.000Z" } } ``` When credentials already exist and `--force` is not set, the JSON envelope is `{ "ok": true, "data": { "alreadyLoggedIn": true, "credentialsPath": "..." } }`. Stdout receives exactly one JSON envelope per invocation (the success or error result). While the command is waiting for the browser callback, a one-line progress event is written to **stderr**: `{"event":"login_pending","consentUrl":"...","state":"..."}`. CI scripts that need the consent URL can read stderr without affecting the parseable stdout payload. Subsequent commands use this credential unless `YORKER_API_KEY` is set in the env, which always wins (see [Auth resolution order](#auth-resolution-order)). #### Error envelope When login fails (timeout waiting for the browser callback, port-bind failure, malformed callback payload, etc.), the JSON envelope is: ```json { "ok": false, "error": { "code": "general_error", "message": "Login timed out after 120s. Try again, or set YORKER_API_KEY manually.", "details": { "exitCode": 1 } } } ``` The same envelope shape is used for every CLI command in `--json` mode. The `code` field uses the strings from the [exit code table](#exit-codes) (`auth_failure` for code 2, `plan_limit` for code 3, etc.). #### Stale-tab safety The consent page mints a key only when you click Authorize, so closing the tab before clicking does not produce an orphaned key. Once you do authorize, only authorize from the tab that the CLI just opened. Closing and reopening the tab voids the previous prompt; opening the URL again from history mints a fresh key against a different `state` token, and the original CLI process will time out without ever receiving it. --- ### `yorker logout` Sign out by deleting local credentials. ```bash yorker logout [--revoke] ``` Removes `~/.yorker/credentials`. The API key remains valid on the server unless you also pass `--revoke`, which calls `DELETE /api/api-keys/self` to delete the key on the server. The endpoint identifies the key from the Authorization header, so no key ID has to be supplied; the row whose hash matches the bearer token is removed. Revoke is best-effort: if the network call fails, the local file is still removed so you do not get stuck holding a credential the CLI considers active. After `--revoke` succeeds, the key cannot be reused. | Flag | Description | |---|---| | `--revoke` | Also delete the API key on the server (via `/api/api-keys/self`). Best-effort; the local file is removed even if the server call fails. | `--json` and `--quiet` work as on every other command. #### `--json` output ```json { "ok": true, "data": { "removed": true, "revoked": true, "revokeError": null, "credentialsPath": "/Users/you/.yorker/credentials" } } ``` `alreadyLoggedOut: true` is added when the local file did not exist. When `--revoke` is set and the server call fails, `revoked` is `false` and `revokeError` is a string describing the failure (the local file is still removed). #### Error envelope ```json { "ok": false, "error": { "code": "general_error", "message": "...", "details": { "exitCode": 1 } } } ``` --- ### `yorker init` Scaffold a new monitoring config in the current directory. Interactive prompts guide you through project name, first monitor URL, type, and frequency. In non-interactive contexts (CI, `--json`, or a non-TTY shell) you must pass `--url` (and optionally the other fields) as flags or the command errors out. ```bash yorker init [--name ] [--url ] [--type ] [--frequency ] [--format file|directory] [--force] ``` | Flag | Description | |---|---| | `--name ` | Project name (skips prompt). | | `--url ` | First monitor URL (skips prompt). Required in non-interactive contexts. | | `--type ` | Monitor type: `http`, `browser`, or `mcp` (skips prompt). Default: `http`. | | `--frequency ` | Check frequency, e.g. `30s`, `5m`, `1h` (skips prompt). Default: `5m`. | | `--format ` | Output layout: `file` (a single `yorker.config.yaml`, the default) or `directory` (a `.yorker/` directory with one YAML file per resource). | | `--force` | Overwrite existing config without asking. | The generated config uses a single default location (`loc_us_east`) and the frequency you choose. Free-tier accounts support one location per check; edit the file to add more locations on a paid plan. HTTP monitors get a starter `status_code: 200` assertion; browser monitors get a `./monitors/.ts` script stub placeholder; MCP monitors just get the endpoint URL. --- ### `yorker deploy` Push your local `yorker.config.yaml` to the control plane. Computes a diff against remote state, displays a Terraform-style plan, and applies changes. ```bash yorker deploy [--dry-run] [--prune] [--force] [--accept-remote] [--wait] ``` | Flag | Description | |---|---| | `--dry-run` | Show the deploy plan without applying changes. | | `--prune` | Delete remote resources not defined in the local config. | | `--force` | Overwrite remote changes (ignore drift). Local config wins. | | `--accept-remote` | Skip drifted resources, keeping their remote changes. | | `--wait` | After a successful create, poll for the first check result from each new monitor (3-minute overall timeout). Exits with code `4` (`PARTIAL_FAILURE`) if any new check's first result is a failure, or if waiting for a first result times out. Useful in CI to catch broken monitors before merging. | > `--force` and `--accept-remote` are mutually exclusive — pass one or the other, not both. #### Deploy pipeline 1. **Load** — reads `yorker.config.yaml` from the current directory. 2. **Interpolate** — resolves `{{secrets.NAME}}`, `{{env.NAME}}`, and `${NAME}` placeholders from environment variables. 3. **Validate** — parses every resource through shared Zod schemas. Fails with all errors collected. 4. **Resolve** — applies cascading defaults (defaults → group → monitor), reads browser script files, builds API payloads. 5. **Fetch remote state** — gets all checks, alerts, SLOs, channels, and maintenance windows from the API. 6. **Detect drift** — compares remote `updatedAt` timestamps against the stored deploy state. See [Drift detection](#drift-detection) below. 7. **Compute plan** — field-level diffs between local and remote state. 8. **Display plan** — Terraform-style plan output. 9. **Apply** — if not `--dry-run`, applies changes in ordered phases. 10. **Save state** — writes `.yorker/.deploy-state.json` with config hashes and remote timestamps. #### Deploy phases Changes are applied in dependency order: | Phase | Action | Why | |---|---|---| | 0 | Create/update notification channels | Channels must exist before alerts or SLOs reference them. | | A | Delete SLOs | Must be deleted before their parent checks. | | B | Delete alerts | Must be deleted before their parent checks. | | C | Delete checks | Safe after dependent resources removed. | | D+E | Create and update checks | New checks get server-assigned IDs needed by alerts and SLOs. | | E2 | Sync check labels | Labels are a separate API, applied after checks exist so new check IDs are known. | | F | Create/update alerts | Alerts reference check IDs and channel IDs. | | G | Create/update SLOs | SLOs reference check IDs and channel IDs. | | H | Create/update maintenance windows | Maintenance windows reference check IDs, so they run after checks exist. | | I | Delete maintenance windows (only with `--prune`) | Stale maintenance windows are only removed when you opt in via `--prune`. | | Z | Delete channels | Runs last so alerts/SLOs referring to channels are gone first. Delete only runs when `--prune` is set, or when a channel's `type` changed in YAML (type changes require delete-and-recreate). | #### Plan output ``` Yorker deploy plan for "my-project" Channels: + CREATE "ops-slack" = UNCHANGED "team-email" Checks: + CREATE http "Users API" (60s, 3 locations) ~ UPDATE http "Homepage" ~ configJson.timeoutMs 30000 -> 15000 - DELETE http "Old Endpoint" = UNCHANGED http "Orders API" Alerts: + CREATE "api-down" (Users API) SLOs: ~ UPDATE "Homepage SLO" ~ targetBasisPoints 9990 -> 9995 Summary: 2 to create, 2 to update, 1 to delete, 2 unchanged ``` | Symbol | Meaning | |---|---| | `+` CREATE | Resource will be created. | | `~` UPDATE | Resource will be updated. Field-level diffs shown below. | | `-` DELETE | Resource will be deleted (requires `--prune` or type change). | | `=` UNCHANGED | No action needed. | #### Drift detection The CLI tracks the state of each resource after every deploy in `.yorker/.deploy-state.json`. On the next deploy, it compares remote `updatedAt` timestamps against the stored state to detect resources modified outside the CLI (e.g., via the web UI). | Local changed? | Remote changed? | Result | |---|---|---| | No | No | Unchanged — skip. | | Yes | No | Normal update — proceed. | | No | Yes | **Drift** — remote was edited outside the CLI. | | Yes | Yes | **Conflict** — both local config and remote were changed. | If drift or conflicts are detected, the deploy aborts with a report: ``` Warning: 1 drifted, 1 conflicting resource(s) modified outside config Checks: ! DRIFT "api-health" (remote changed since last deploy) Alerts: ! CONFLICT "api-health:latency" (both local and remote changed) Use --force to overwrite remote changes, or --accept-remote to keep them. ``` Resolution options: | Flag | Behavior | |---|---| | *(default)* | Abort with drift/conflict report. | | `--force` | Local config wins — overwrite remote changes. | | `--accept-remote` | Skip drifted/conflicting resources — keep remote as-is. | The deploy state file `.yorker/.deploy-state.json` is per-machine state. Add it to your `.gitignore` to avoid committing it. Every successful `yorker pull` rewrites this file with a fresh snapshot of remote state, so the next deploy treats everything as a clean baseline. --- ### `yorker diff` Show changes between local config and remote state without applying them. ```bash yorker diff ``` Displays the same Terraform-style plan as `yorker deploy --dry-run`. Designed for CI pipelines and quick checks — see [CI/CD Integration](/docs/guides/ci-cd) for full workflow examples. --- ### `yorker pull` Export remote monitors, alerts, SLOs, and notification channels to a local config. The reverse of `yorker deploy`. ```bash yorker pull [--output ] [--format file|directory] [--monitor ] [--force] ``` | Flag | Description | |---|---| | `-o, --output ` | Output path. Default: `yorker.config.yaml` in file format, or `.yorker/` in directory format. | | `--format ` | Output layout: `file` (single `yorker.config.yaml`, default) or `directory` (a `.yorker/` tree with one YAML file per resource). | | `--monitor ` | Pull a single monitor by name or ID. | | `--force` | Overwrite existing config file and scripts. | Fetches all monitors, alerts, SLOs, and notification channels and writes a config file that `yorker deploy` can consume. Browser monitor scripts are extracted to `./monitors/.ts`, where `` is the monitor name lowercased with non-alphanumeric characters replaced by hyphens (e.g., `Login Flow` becomes `login-flow.ts`). > **`yorker pull` does not export maintenance windows and overwrites your entire config file.** If you manage maintenance windows through YAML, running `pull` will erase them from your local file (remote maintenance windows are not touched, but they will not reappear in the re-pulled YAML). If you need to round-trip safely, either avoid `pull` on projects that use `maintenanceWindows`, or re-add them to the YAML after each pull. A subsequent `yorker deploy` without `--prune` leaves remote maintenance windows alone; `yorker deploy --prune` will delete any remote maintenance windows that are not in the (now empty) local YAML. --- ### `yorker import` > **Coming soon.** The `import` command is a scaffold today — running it reports the selected source, the source and output paths, and a link to the changelog where the release will land, then exits with code `1`. The importers themselves ship in a follow-up release. Import existing monitors from another synthetic monitoring tool into a Yorker config. The resulting YAML is ready to deploy with `yorker deploy`, with inline `TODO` comments on anything that doesn't translate cleanly. ```bash yorker import --from [--output ] [path] ``` | Flag / Argument | Description | |---|---| | `--from ` | **Required.** Source tool to import from. See supported sources below. | | `--output ` | Directory to write the generated Yorker YAML into. Default: `.` (current directory). | | `[path]` | Path to the source repo or config file (e.g. `./src/__checks__` for Checkly, `./tests` for a Playwright project). | **Supported sources** (planned): | Source | `--from` value | |---|---| | Checkly | `checkly` | | Datadog Synthetics | `datadog-synthetics` | | Better Stack | `better-stack` | | Pingdom | `pingdom` | | Grafana Synthetic Monitoring | `grafana-synthetic-monitoring` | | Playwright | `playwright` | Example (once available): ```bash # Import a Checkly project yorker import --from checkly ./src/__checks__ # Import a Playwright test suite as browser monitors yorker import --from playwright ./tests --output ./yorker/ ``` Watch the [changelog](/changelog) for release dates. Until the importers land, the [comparison pages](/compare) document the migration story for each source. --- ### `yorker validate` Validate your config without deploying. Runs the full load, interpolate, and validate pipeline without contacting the API. ```bash yorker validate ``` Validation includes YAML syntax, Zod schema validation, secret interpolation, browser script file existence, frequency range checks, name uniqueness, SLO/alert cross-references, channel resolution, and maintenance-window time ranges. ``` Config is valid: 5 monitor(s), 2 SLO(s) ``` On failure, all errors are collected: ``` 3 config error(s): monitors[Homepage].httpConfig.url: Invalid url monitors[Login Flow]: cannot read script file "./monitors/missing.ts" slos[API SLO]: references monitor "Nonexistent" which does not exist ``` --- ### `yorker status` Show a status overview of all monitors. ```bash yorker status [--watch] [--interval ] ``` | Flag | Description | |---|---| | `--watch` | Continuously refresh. In an interactive TTY the screen is cleared and redrawn in place. In `--json` mode each cycle emits a single newline-delimited JSON object. When stdout is piped (non-TTY, non-JSON), each snapshot is appended with a `--- Status @ ---` header. Press `Ctrl+C` to exit. | | `--interval ` | Refresh interval for `--watch` (default: `30s`, range: `5s` to `1h`). Ignored without `--watch`. | Displays each monitor with its enabled/paused state, type, frequency, health, and recent-result sparkline. Exits with code `10` when any monitor is unhealthy. --- ### `yorker dashboard` Open an interactive full-screen status dashboard in your terminal. Polls the API on a configurable interval and renders monitor health, recent results, and sparklines. ```bash yorker dashboard [--interval ] ``` | Flag | Description | |---|---| | `--interval ` | Refresh interval (default: `30s`, range: `5s` to `1h`). | **Keybindings** (list view): | Key | Action | |---|---| | `↑` / `k` | Move selection up | | `↓` / `j` | Move selection down | | `Enter` | Open detail view for the selected monitor | | `/` | Filter monitors by name | | `r` | Refresh now (outside the polling interval) | | `q` / `Ctrl+C` | Quit | In the detail view, press `Esc` to return to the list, `q` to quit, or `r` to refresh. This is the interactive TUI (singular `dashboard`). For installing HyperDX / ClickStack dashboard packs, see `yorker dashboards install` below. --- ### `yorker dashboards install` Install pre-built Yorker dashboards into HyperDX (self-hosted) or ClickStack Cloud. See [Install Dashboards](/docs/guides/install-dashboards) for full setup. ```bash # Self-hosted HyperDX yorker dashboards install --hyperdx-api-key # ClickStack Cloud yorker dashboards install --mode clickstack_cloud \ --clickstack-org-id \ --clickstack-service-id \ --clickstack-api-key-id \ --clickstack-api-secret ``` | Flag | Description | |---|---| | `--mode ` | `self_hosted` (default) or `clickstack_cloud` (env: `HYPERDX_MODE`) | | `--hyperdx-api-key ` | HyperDX API key for self-hosted mode (env: `HYPERDX_API_KEY`) | | `--hyperdx-url ` | Override HyperDX API URL for self-hosted (default: `https://www.hyperdx.io`) | | `--clickstack-org-id ` | ClickHouse Cloud organization ID (env: `CLICKSTACK_ORG_ID`) | | `--clickstack-service-id ` | ClickHouse Cloud service ID (env: `CLICKSTACK_SERVICE_ID`) | | `--clickstack-api-key-id ` | ClickHouse Cloud API key ID (env: `CLICKSTACK_API_KEY_ID`) | | `--clickstack-api-secret ` | ClickHouse Cloud API key secret (env: `CLICKSTACK_API_SECRET`) | | `--packs ` | Comma-separated subset: `overview`, `deep-dive`, `status-page`, `trace-correlation` | | `--force` | Skip duplicate check (may create additional copies) | --- ### `yorker log` View config change history. Shows what changed, when, and how. ```bash yorker log [--type ] [--name ] [--source ] [--limit ] [--offset ] ``` | Flag | Description | |---|---| | `--type ` | Filter by resource type (`check`, `alert`, `slo`, `channel`). | | `--name ` | Filter by resource name (case-insensitive substring match). | | `--source ` | Filter by change source (`ui`, `yaml`, `api`). | | `--limit ` | Number of changes to show (default: 20, max: 200). | | `--offset ` | Skip first N changes for pagination (cannot be used together with `--name`). | ``` Config changes (showing 5): Time Action Type Name Source 2m ago create check api-health yaml 5m ago update alert api-health:p95 ui 1h ago delete channel old-slack yaml 2h ago update slo availability api 3h ago create check login-flow yaml ``` Use `--json` for machine-readable output in CI pipelines. --- ### `yorker test` Run HTTP monitors locally against their configured URLs. Uses the same config pipeline as deploy, so all defaults, auth, and secrets are applied identically. ```bash yorker test ``` ``` Running monitors locally... HTTP Homepage ... 200 (142ms) HTTP Users API ... 200 (89ms) Browser Login Flow (4 steps) 1. Navigate 2. Log in 3. Dashboard loads 4. Check account Browser monitors require remote execution — use `yorker deploy` then check results MCP Docs Server MCP monitors require remote execution — use `yorker deploy` then check results ``` Only HTTP monitors are exercised locally. Browser and MCP monitors are listed (browser monitors also display extracted step markers) but skipped — deploy them and view results remotely. --- ### `yorker completions [shell]` Generate shell completion scripts. Auto-detects your shell if the argument is omitted. ```bash yorker completions # auto-detect yorker completions bash yorker completions zsh yorker completions fish ``` Pipe the output to the appropriate file for your shell. For example: ```bash yorker completions zsh > ~/.zfunc/_yorker ``` --- ## Monitor Commands ### `yorker monitors list` List all monitors. The output includes each monitor's name, type, frequency, location count, and any labels attached to the check. ```bash yorker monitors list [--type ] [--status ] ``` | Flag | Description | |---|---| | `--type ` | Filter by type: `http`, `browser`, or `mcp`. | | `--status ` | Filter by status: `enabled` or `paused`. | In `--json` mode, each monitor entry includes a `labels` array (omitted when label lookup failed, e.g. due to permissions or a transient API error). --- ### `yorker monitors get ` Show detailed information about a monitor, including recent results. ```bash yorker monitors get "Homepage" yorker monitors get chk_abc123 ``` Displays monitor details (ID, type, status, frequency, locations, URL or endpoint) and a table of recent results with response times and status codes. --- ### `yorker monitors create` Create a new HTTP monitor imperatively. Browser and MCP monitors must be created via `yorker deploy` from YAML. ```bash yorker monitors create --name "API Health" --type http --url https://api.example.com/health [--method GET] [--frequency 5m] [--locations loc_us_east,loc_eu_central] ``` | Flag | Required | Description | |---|---|---| | `--name ` | Yes | Monitor name. | | `--type ` | Yes | Must be `http`. | | `--url ` | Yes | URL to monitor. | | `--method ` | No | HTTP method (default: `GET`). | | `--frequency ` | No | Check frequency (default: `5m`). | | `--locations ` | No | Comma-separated location IDs (default: all active hosted locations). | --- ### `yorker monitors edit ` Edit an existing monitor. ```bash yorker monitors edit "Homepage" --frequency 1m --add-location loc_eu_central ``` | Flag | Description | |---|---| | `--name ` | New monitor name. | | `--frequency ` | New frequency. | | `--add-location ` | Add a location. | | `--remove-location ` | Remove a location. | | `--yes` | Skip confirmation prompt. | --- ### `yorker monitors delete ` Delete a monitor and all its results and alert rules. ```bash yorker monitors delete "Old Endpoint" [--yes] ``` Requires confirmation unless `--yes` is passed. --- ### `yorker monitors pause ` Pause a running monitor. ```bash yorker monitors pause "Homepage" ``` --- ### `yorker monitors resume ` Resume a paused monitor. ```bash yorker monitors resume "Homepage" ``` --- ### `yorker monitors analyze ` Run a deep insights analysis on a monitor. Sends recent results and context to the Yorker insights engine and returns a classified summary (type, severity, confidence, summary text). ```bash yorker monitors analyze "Homepage" yorker monitors analyze chk_abc123 yorker monitors analyze chk_abc123 --json ``` Output in human mode: ``` Type degradation Severity warning Confidence 0.87 Summary Response times increased 3x over the last hour across US-East, correlated with an upstream dependency slowdown. Model claude-sonnet-4-20250514 Generated Apr 9, 2026, 3:23:04 PM UTC Deep analysis usage: 2/5 used for this resource. ``` In `--json` mode, emits the full validated response envelope (`insight`, `stale`, `deepAnalysisCount`, `deepAnalysisLimit`) under the standard `{ ok: true, data: ... }` envelope. Deep analysis is rate-limited per monitor (5-minute cooldown between runs, 5 lifetime calls per monitor) and per team (50 per month). When rate-limited, the command exits with code `3` and prints a message explaining how long to wait or when the monthly quota resets. --- ## Results Commands ### `yorker results list ` List check results for a monitor. ```bash yorker results list "Homepage" [--limit 20] [--status success] [--since 24h] ``` | Flag | Description | |---|---| | `--limit ` | Number of results (default: `20`, max: `200`). | | `--offset ` | Skip first N results for pagination. Cannot be combined with `--status` or `--since`. | | `--status ` | Filter: `success`, `failure`, `error`, `timeout`. Applied client-side. | | `--since ` | Only show results from this period (e.g. `1h`, `24h`, `7d`). Applied client-side. | > `--offset` is server-side pagination; `--status` and `--since` are client-side filters. Mixing them would produce inconsistent page sizes, so the CLI rejects the combination. Use `--limit` + re-run with a later `--since` if you need to page through filtered results. --- ### `yorker results get ` Show full details for a specific check result. ```bash yorker results get "Homepage" res_abc123 ``` Includes timing breakdown (DNS, TLS, TTFB, content transfer), assertions (pass/fail), screenshots, Web Vitals (browser monitors), tool-call results (MCP monitors), network requests, and console errors. --- ### `yorker results tail ` Live-stream new results as they arrive. Long-running command that polls at a configurable interval. ```bash yorker results tail "Homepage" [--interval 30s] ``` | Flag | Description | |---|---| | `--interval ` | Poll interval (default: `30s`, range: `5s` to `1h`). | ``` Tailing Homepage (every 30s, Ctrl+C to stop) Apr 9, 2026, 12:34:56 PM UTC ✓ 200 US East Coast 142ms Apr 9, 2026, 12:35:26 PM UTC ✓ 200 EU Central 89ms Apr 9, 2026, 12:36:56 PM UTC ✗ timeout US East Coast 30000ms connection timeout ``` Timestamps are formatted as localized US English strings using the team's configured timezone (defaults to UTC). In `--json` mode, outputs one JSON object per result (newline-delimited). --- ## Alert Commands ### `yorker alerts list` List alert instances. ```bash yorker alerts list [--all] [--monitor "Homepage"] [--state active,acknowledged] ``` | Flag | Description | |---|---| | `--all` | Include resolved and recovered alerts (default: active and acknowledged only). | | `--monitor ` | Filter by monitor. | | `--state ` | Comma-separated states: `active`, `acknowledged`, `recovered`, `resolved`. | The command returns at most 100 alert instances per invocation (the most recent by start time). For larger historical windows, use `yorker alerts history` or the REST API with pagination. --- ### `yorker alerts ack ` Acknowledge an active alert. ```bash yorker alerts ack ainst_abc123 ``` --- ### `yorker alerts resolve ` Manually resolve an alert. ```bash yorker alerts resolve ainst_abc123 ``` --- ### `yorker alerts analyze ` Run a deep insights analysis on an alert instance. Sends context about the alert (monitor, recent results, correlations) to the Yorker insights engine and returns a classified summary with a type, severity, confidence score, and summary text. ```bash yorker alerts analyze ainst_abc123 yorker alerts analyze ainst_abc123 --json ``` Output in human mode matches `yorker monitors analyze` — labeled fields for `Type`, `Severity`, `Confidence`, `Summary`, `Model`, and `Generated`, followed by a usage footer. In `--json` mode, emits the full validated response envelope (`insight`, `stale`, `deepAnalysisCount`, `deepAnalysisLimit`) under the standard `{ ok: true, data: ... }` envelope. Deep analysis is rate-limited per alert instance (5-minute cooldown, 5 lifetime calls per instance) and per team (50 per month). When rate-limited, the command exits with code `3` and prints a message explaining how long to wait or when the monthly quota resets. --- ### `yorker alerts history` Show alert history. ```bash yorker alerts history [--monitor "Homepage"] [--since 7d] [--limit 20] ``` | Flag | Description | |---|---| | `--monitor ` | Filter by monitor. | | `--since ` | Time window (e.g. `30m`, `24h`, `7d`). | | `--limit ` | Number of alerts (default: `20`, max: `200`). | --- ### `yorker alerts rules list` List alert rules across monitors. ```bash yorker alerts rules list [--monitor "Homepage"] ``` --- ### `yorker alerts rules create` Create a new alert rule with a single condition. For multi-condition rules, use `yorker.config.yaml` and `yorker deploy`. ```bash yorker alerts rules create --monitor "Homepage" --condition "consecutive_failures >= 3" --channel nch_abc123 [--name "homepage-down"] [--severity critical] ``` | Flag | Required | Description | |---|---|---| | `--monitor ` | Yes | Monitor to attach the rule to. | | `--condition ` | Yes | Alert condition (see formats below). | | `--channel ` | Yes | Notification channel ID (`nch_...`). | | `--name ` | No | Optional rule name. | | `--severity ` | No | Severity for SSL/certificate conditions: `critical`, `warning`, or `info`. Ignored for non-certificate conditions. | #### Condition formats | Syntax | Type | |---|---| | `consecutive_failures >= 3` | Trigger after N consecutive failures. | | `response_time > 5000` | Trigger if response time exceeds N ms. | | `multi_location >= 2` | Trigger if N+ locations fail simultaneously. | | `ssl_expiry < 14` | Trigger if SSL cert expires within N days. | | `ssl_certificate_changed` | Trigger when the leaf certificate fingerprint changes between runs. | | `ssl_self_signed` | Trigger when a self-signed or untrusted-root certificate is detected. | | `ssl_protocol < TLSv1.3` | Trigger when the TLS handshake negotiates a protocol older than the minimum. Allowed minimums: `TLSv1.2`, `TLSv1.3`. | --- ## Location Commands The `yorker locations` command group manages private locations and runner keys. ### `yorker locations list` List your private locations. By default only private locations are shown; pass `--all` to include the 14 hosted locations as well. ```bash yorker locations list # private locations only yorker locations list --all # private + hosted ``` | Flag | Description | |---|---| | `--all` | Include hosted locations in the output. | Shows each location's ID, type (`hosted` / `private`), display name, region, health status, and (for private locations) last heartbeat. --- ### `yorker locations create` Create a private location and auto-provision an initial runner key. ```bash yorker locations create --name --display-name "" [--region ] ``` | Flag | Required | Description | |---|---|---| | `--name ` | Yes | Unique lowercase slug (e.g. `staging-eu`). | | `--display-name ` | Yes | Human-readable display name. | | `--region ` | No | Region identifier (default: `private`). | The runner key secret is printed **once** — save it immediately. The command also prints a ready-to-run Docker snippet for starting the runner. --- ### `yorker locations delete ` Delete a private location. Fails if any monitors still reference it. Also revokes every runner key associated with the location. The argument is the location ID (`loc_...`). ```bash yorker locations delete loc_staging_eu [--yes] ``` --- ### `yorker locations keys list ` List runner keys for a private location. Only the key ID, name, prefix, and last-used time are returned — the secret is never exposed again after creation. ```bash yorker locations keys list loc_staging_eu ``` --- ### `yorker locations keys create ` Provision a new runner key for a private location. The secret is printed **once**, followed by a ready-to-run Docker snippet. ```bash yorker locations keys create loc_staging_eu [--name "