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

Install globally with npm:

npm install -g @yorker/cli

On macOS or Linux you can also install with Homebrew:

brew install reverse-sweep-ltd/tap/yorker

Or locally in a project:

npm install --save-dev @yorker/cli

Authentication

For interactive use, run yorker login. The CLI prints a short XXXX-XXXX confirmation code, opens your browser, and waits for you to click Authorize. On success it stores a fresh API key at ~/.yorker/credentials (mode 0600).

yorker login

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

export YORKER_API_KEY=sk_your_key_here

The CLI resolves auth in this 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).

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:

Environment Variables

Exit Codes

Commands

yorker login

Authenticate the CLI by approving access in your browser.

yorker login [--force]

The CLI uses a device-code flow:

1. The CLI calls the server to get a fresh XXXX-XXXX confirmation code that expires in 10 minutes.
2. It prints the code in your terminal and opens your browser to the consent page.
3. You sign in (if you weren't already), confirm the code in the browser matches the one in your terminal, then click Authorize.
4. The CLI polls every 2 seconds for the result. On success it picks up a fresh API key labelled CLI <hostname> and writes it to ~/.yorker/credentials with mode 0600.

Confirming the code is the phishing protection. If the code in the browser doesn't match the one in your terminal, you are on a different device's consent page; cancel and run yorker login again. You can revoke the key any time from Settings > API Keys, or with 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.

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. YORKER_API_KEY environment variable
2. ~/.yorker/credentials
3. 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

  Open this URL in your browser:
    https://yorkermonitoring.com/cli/auth?code=ABCD-EFGH

  Confirm this code matches the one shown there:

    ┌─────────────┐
    │  ABCD-EFGH  │
    └─────────────┘

  Waiting for authorization...

  ✓ 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

{
  "ok": true,
  "data": {
    "apiUrl": "https://yorkermonitoring.com",
    "credentialsPath": "/Users/you/.yorker/credentials",
    "createdAt": "2026-05-09T14: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). After the device code is minted, a one-line progress event is written to stderr so CI scripts that want the verification URL can read it without affecting the parseable stdout payload:

{"event":"awaiting_consent","code":"ABCD-EFGH","verification_url":"https://yorkermonitoring.com/cli/auth?code=ABCD-EFGH"}

Subsequent commands use the persisted credential unless YORKER_API_KEY is set in the env, which always wins (see Auth resolution order).

Error envelope

When login fails (the 10-minute code TTL was reached without authorization, a network error during init, etc.), the JSON envelope is:

{
  "ok": false,
  "error": {
    "code": "general_error",
    "message": "Login session expired. Run `yorker login` again.",
    "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 (auth_failure for code 2, plan_limit for code 3, etc.).

Stale-tab safety

The consent page only mints a key when you click Authorize, so closing the tab before clicking does not produce an orphaned key. The code expires after 10 minutes, after which the CLI prints a clean error and you can run yorker login again. Each run mints a fresh code, so an old verification URL pulled from your browser history will simply land on a "Code expired" page instead of authorizing access.

yorker logout

Sign out by deleting local credentials.

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.

--json and --quiet work as on every other command.

--json output

{
  "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

{
  "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.

yorker init [--name <name>] [--url <url>] [--type <type>] [--frequency <freq>] [--format file|directory] [--force]

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/<name>.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.

yorker deploy [--dry-run] [--prune] [--force] [--accept-remote] [--wait]

--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 to group to 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 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:

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

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).

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:

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.

yorker diff

Displays the same Terraform-style plan as yorker deploy --dry-run. Designed for CI pipelines and quick checks. See CI/CD Integration for full workflow examples.

yorker pull

Export remote monitors, alerts, SLOs, and notification channels to a local config. The reverse of yorker deploy.

yorker pull [--output <path>] [--format file|directory] [--monitor <name>] [--force]

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/<slug>.ts, where <slug> 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.

yorker import --from <source> [--output <path>] [path]

Supported sources (planned):

Example (once available):

# 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 for release dates. Until the importers land, the comparison pages 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.

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.

yorker status [--watch] [--interval <duration>]

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.

yorker dashboard [--interval <duration>]

Keybindings (list view):

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 for full setup.

# Self-hosted HyperDX
yorker dashboards install --hyperdx-api-key <your-key>

# ClickStack Cloud
yorker dashboards install --mode clickstack_cloud \
  --clickstack-org-id <org-uuid> \
  --clickstack-service-id <service-uuid> \
  --clickstack-api-key-id <key-id> \
  --clickstack-api-secret <key-secret>

yorker log

View config change history. Shows what changed, when, and how.

yorker log [--type <type>] [--name <name>] [--source <source>] [--limit <n>] [--offset <n>]

  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.

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.

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:

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.

yorker monitors list [--type <type>] [--status <status>]

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 <name-or-id>

Show detailed information about a monitor, including recent results.

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.

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]

yorker monitors edit <name-or-id>

Edit an existing monitor.

yorker monitors edit "Homepage" --frequency 1m --add-location loc_eu_central

yorker monitors delete <name-or-id>

Delete a monitor and all its results and alert rules.

yorker monitors delete "Old Endpoint" [--yes]

Requires confirmation unless --yes is passed.

yorker monitors pause <name-or-id>

Pause a running monitor.

yorker monitors pause "Homepage"

yorker monitors resume <name-or-id>

Resume a paused monitor.

yorker monitors resume "Homepage"

yorker monitors analyze <name-or-id>

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).

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 <monitor>

List check results for a monitor.

yorker results list "Homepage" [--limit 20] [--status success] [--since 24h]

--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 <monitor> <result-id>

Show full details for a specific check result.

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 <monitor>

Live-stream new results as they arrive. Long-running command that polls at a configurable interval.

yorker results tail "Homepage" [--interval 30s]

  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.

yorker alerts list [--all] [--monitor "Homepage"] [--state active,acknowledged]

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 <instance-id>

Acknowledge an active alert.

yorker alerts ack ainst_abc123

yorker alerts resolve <instance-id>

Manually resolve an alert.

yorker alerts resolve ainst_abc123

yorker alerts analyze <instance-id>

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.

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.

yorker alerts history [--monitor "Homepage"] [--since 7d] [--limit 20]

yorker alerts rules list

List alert rules across monitors.

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.

yorker alerts rules create --monitor "Homepage" --condition "consecutive_failures >= 3" --channel nch_abc123 [--name "homepage-down"] [--severity critical]

Condition formats

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.

yorker locations list          # private locations only
yorker locations list --all    # private + hosted

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.

yorker locations create --name <slug> --display-name "<name>" [--region <id>]

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 <location-id>

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_...).

yorker locations delete loc_staging_eu [--yes]

yorker locations keys list <location-id>

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.

yorker locations keys list loc_staging_eu

yorker locations keys create <location-id>

Provision a new runner key for a private location. The secret is printed once, followed by a ready-to-run Docker snippet.

yorker locations keys create loc_staging_eu [--name "<label>"]

yorker locations keys revoke <location-id> <key-id>

Revoke a runner key by its ID (rkey_...). Any runners using the revoked key lose access immediately.

yorker locations keys revoke loc_staging_eu rkey_abc123 [--yes]

CI/CD Integration

Validate on push, preview changes on PRs, deploy on merge. See the full CI/CD Integration guide for complete GitHub Actions and GitLab CI workflows with PR commenting and JSON output parsing.

# GitHub Actions: quick start
- run: npm install -g @yorker/cli
- run: yorker validate                          # every push
- run: yorker diff                              # PR preview
- run: yorker deploy --force                    # merge to main (CI owns the config)
  if: github.ref == 'refs/heads/main'

Use --force in automated pipelines where the config file is the source of truth. Use --accept-remote if you want CI to skip resources that were edited manually.

Set YORKER_API_KEY and any YORKER_SECRET_* variables at the job or workflow level so all steps (including validate) can resolve {{secrets.*}} placeholders.

Command Tree

yorker
├── login [--force]
├── logout [--revoke]
├── init [--name] [--url] [--type] [--frequency] [--format file|directory] [--force]
├── deploy [--dry-run] [--prune] [--force] [--accept-remote] [--wait]
├── diff
├── pull [--output] [--format file|directory] [--monitor] [--force]
├── validate
├── status [--watch] [--interval]
├── test
├── dashboard [--interval]               # interactive TUI
├── dashboards
│   └── install [--mode] [--hyperdx-api-key] [--clickstack-*] [--packs]
├── log [--type] [--name] [--source] [--limit] [--offset]
├── completions [bash|zsh|fish]
├── import --from <source> [--output] [path]  # coming soon
├── monitors
│   ├── list [--type] [--status]
│   ├── get <name-or-id>
│   ├── create --name --type [--url] [--method] [--frequency] [--locations]
│   ├── edit <name-or-id> [--name] [--frequency] [--add-location] [--remove-location] [--yes]
│   ├── delete <name-or-id> [--yes]
│   ├── pause <name-or-id>
│   └── resume <name-or-id>
├── results
│   ├── list <monitor> [--limit] [--offset] [--status] [--since]
│   ├── get <monitor> <result-id>
│   └── tail <monitor> [--interval]
├── alerts
│   ├── list [--all] [--monitor] [--state]
│   ├── ack <instance-id>
│   ├── resolve <instance-id>
│   ├── history [--monitor] [--since] [--limit]
│   └── rules
│       ├── list [--monitor]
│       └── create --monitor --condition --channel [--name] [--severity]
└── locations
    ├── list [--all]
    ├── create --name --display-name [--region]
    ├── delete <location-id> [--yes]
    └── keys
        ├── list <location-id>
        ├── create <location-id> [--name]
        └── revoke <location-id> <key-id> [--yes]