Yorker CLI

Precision synthetic monitoring as code. Plain YAML, full CLI, OTel-native.

Install

npm install -g @yorker/cli
# or: pnpm add -g @yorker/cli
# or: yarn global add @yorker/cli

On macOS or Linux you can also install with Homebrew:

brew install reverse-sweep-ltd/tap/yorker

Requires Node.js 20 or later. The yorker binary is on your PATH after a global install. The github:Reverse-Sweep-Ltd/yorker install path does not currently expose the binary.

Authenticate

For interactive use on a workstation, run:

yorker login

The command opens a browser, mints an API key for your team after you click Authorize, and stores it at ~/.yorker/credentials (mode 0600). Run yorker logout to sign out (--revoke also deletes the key on the server).

For CI, Docker, and other headless contexts, set YORKER_API_KEY instead. Generate a key from Settings > API Keys in the dashboard. Keys start with sk_.

export YORKER_API_KEY=sk_...

The CLI resolves auth in this precedence order on every invocation:

1. YORKER_API_KEY environment variable
2. ~/.yorker/credentials (written by yorker login)
3. Otherwise, the command exits with code 2 (authentication failure).

5-minute quickstart

1. Authenticate. Either run yorker login (interactive) or export an API key from https://yorkermonitoring.com/dashboard/settings:

   yorker login
   # or, for CI / headless contexts:
   export YORKER_API_KEY=sk_...

2. Create your first monitor:

   yorker monitors create \
     --name "Example homepage" \
     --type http \
     --url https://example.com

3. Watch results land:

   yorker results tail "Example homepage"

Full guide: https://yorkermonitoring.com/docs.

Commands

Every command supports --json, --quiet, --no-color, --verbose, and --api-url.

Configuration

| Command | What it does | |---|---| | yorker init | Scaffold yorker.config.yaml (or .yorker/) with a starter monitor. | | yorker validate | Validate yorker.config.yaml (or .yorker/) without deploying. | | yorker deploy | Apply the config: create, update, or pause monitors, alerts, SLOs, channels. | | yorker diff | Show the change set between local config and remote state. | | yorker pull | Export remote monitors, alerts, SLOs, channels back to YAML. | | yorker test | Run HTTP monitors locally and print step plans for browser monitors. Browser and MCP monitors require remote execution. |

Monitors

| Command | What it does | |---|---| | yorker monitors list | List monitors, with optional --type and --status filters. | | yorker monitors get <name-or-id> | Show monitor config plus the last few results. | | yorker monitors create | Create a new HTTP monitor (browser and MCP monitors require yorker deploy). | | yorker monitors edit <name-or-id> | Edit name, frequency, or location set on an existing monitor. | | yorker monitors delete <name-or-id> | Delete a monitor and all its results. | | yorker monitors pause <name-or-id> / resume | Pause or resume scheduling. | | yorker monitors analyze <name-or-id> | Deep-analyze a monitor: suspects, recent regressions, next steps. |

Results

| Command | What it does | |---|---| | yorker results list <monitor> | List recent results, with --status and --since filters. | | yorker results get <monitor> <result-id> | Show a single check run in full: timing, vitals, steps, screenshots. | | yorker results tail <monitor> | Live-stream new results as they arrive. --json emits NDJSON. | | yorker status | One-shot health roll-up across every monitor. Exit 10 if any are down. | | yorker dashboard | Full-screen interactive status dashboard (TTY only). |

Alerts and incidents

| Command | What it does | |---|---| | yorker alerts list | Active and acknowledged alerts (use --all to include resolved and recovered, capped at 100 most recent). | | yorker alerts ack <ainst_id> / resolve | Acknowledge or manually resolve an alert. | | yorker alerts history | Alert history across all monitors. | | yorker alerts analyze <ainst_id> | Deep-analyze an alert instance. | | yorker alerts rules list / create | List or create alert rules (per-monitor conditions and channels). | | yorker incidents list | Incidents grouped from correlated alerts. | | yorker incidents get <inc_id> | Full incident detail: timeline, members, observations. | | yorker incidents ack / close / reopen / note | Lifecycle commands and timeline notes. | | yorker incidents analyze <inc_id> | Deep-analyze an incident: suspects, ruled-out causes, next steps. | | yorker incidents watch | Stream lifecycle events as NDJSON (Ctrl+C to stop). |

Locations

| Command | What it does | |---|---| | yorker locations list | Private locations by default; --all includes hosted locations alongside your private ones. | | yorker locations create | Create a private location and emit a Docker run snippet for the runner. | | yorker locations delete <loc_id> | Delete a private location and revoke its keys. | | yorker locations keys list / create / revoke | Manage runner keys for a private location. |

Other

| Command | What it does | |---|---| | yorker dashboards install | Install the Yorker dashboard packs into HyperDX or ClickStack Cloud. | | yorker log | View the config-change history (who changed what, from where). | | yorker completions <bash\|zsh\|fish> | Print a shell completion script. | | yorker import --from <tool> | Import monitors from another tool (Checkly, Datadog Synthetics, etc.; coming soon). |

Run yorker <command> --help for full flag detail on any command.

Configuration

Environment variables

| Variable | Required | Description | |---|---|---| | YORKER_API_KEY | Yes (unless logged in via yorker login) | API key for authentication. Keys start with sk_. Wins over ~/.yorker/credentials when both are set. | | YORKER_API_URL | No | Control plane URL. Defaults to https://yorkermonitoring.com. | | YORKER_SECRET_<NAME> | No | Secret value for {{secrets.NAME}} references in yorker.config.yaml. The placeholder name (NAME) must also appear in the top-level secrets: allowlist in your config; otherwise validation rejects it as a disallowed secret/env placeholder. |

yorker.config.yaml shape

project: my-app

# Allowlist every env var that may be interpolated as
# ${X} / {{env.X}} / {{secrets.X}} elsewhere in this file.
# Without this list, interpolation is disabled and any placeholder
# becomes a validation error.
secrets:
  - SLACK_WEBHOOK_URL

alertChannels:
  ops-slack:
    type: slack
    webhookUrl: "{{secrets.SLACK_WEBHOOK_URL}}"

defaults:
  frequency: 1m
  # Free tier supports 1 location; paid tiers support more.
  locations:
    - loc_us_east

monitors:
  - name: homepage
    type: http
    url: https://example.com
    assertions:
      - type: status_code
        value: 200
      - type: body_contains
        value: "Welcome"
    alerts:
      - conditions:
          - type: consecutive_failures
            count: 3
        channels:
          - "@ops-slack"

  - name: checkout-flow
    type: browser
    frequency: 5m
    script: ./scripts/checkout.spec.ts
    locations:
      - loc_us_east

Full schema (channels, defaults, groups, SLOs, maintenance windows): https://yorkermonitoring.com/docs/reference/configuration.

Monitoring as code

Edit yorker.config.yaml, then yorker validate, yorker diff, yorker deploy. Adopting the workflow on an existing account? yorker pull re-exports remote state to YAML.

Examples and recipes: https://yorkermonitoring.com/docs/guides/monitoring-as-code.

Troubleshooting

Yorker is not authenticated. Run yorker login (interactive workstation) or set YORKER_API_KEY=sk_... (CI / headless).

401 Unauthorized on every command. The key is wrong, expired, or was revoked. Generate a new one at https://yorkermonitoring.com/dashboard/settings and re-export it.

fetch failed / connection timeout. Confirm YORKER_API_URL is reachable from where you are running the CLI. The default is https://yorkermonitoring.com. If you are behind a corporate proxy, set HTTPS_PROXY.

drift detected on yorker deploy. Someone changed a monitor in the UI after your last deploy. Run yorker diff to see what changed, then either --force to overwrite remote or --accept-remote to keep the UI changes.

CLI version drift across the team. Pin the install to a specific version: npm install -g @yorker/cli@<version> (or the pnpm / yarn equivalent).

Links

• Documentation: https://yorkermonitoring.com/docs
• CLI reference: https://yorkermonitoring.com/docs/reference/cli
• Status: https://yorkermonitoring.com/status
• Support: [email protected]
• Issues: https://github.com/Reverse-Sweep-Ltd/yorker/issues