feat(cli): add checks list/get commands with typed formatters by MichaelHogers · Pull Request #1233 · checkly/checkly-cli

MichaelHogers · 2026-02-23T10:20:46Z

Summary

Add checkly checks list and checkly checks get CLI commands for viewing checks, results, and error groups from the terminal.

REST clients for checks, check-results, check-statuses, check-groups, error-groups
Formatters with typed field definitions (DetailField<T>, ColumnDef<T>) — fields defined once, rendered for both terminal and markdown
Unit tests for formatters and render primitives, e2e tests for both commands

Also adds a new e2e testing account with no checks, representing a new user, to cover any potential edge cases we may miss in our own e2e prod account.

config.emptyApiKey = process.env.CHECKLY_EMPTY_API_KEY
config.emptyAccountId = process.env.CHECKLY_EMPTY_ACCOUNT_ID

Test plan

vitest --run src/formatters/__tests__/ src/commands/checks/__tests__/ — 115 tests pass
E2E: checks-list.spec.ts, checks-get.spec.ts (require prod env)

Add `checkly checks list` and `checkly checks get` commands with REST clients, formatters, and e2e tests. Formatters use typed field definitions (DetailField, ColumnDef) with generic renderDetailFields/renderTable primitives, defining fields once and rendering them for both terminal and markdown output formats.

- Extract appendErrors/appendAssets helpers in check-result-detail - Collapse duplicated formatBody try/catch branches - De-duplicate Tags column definition in checks table - Simplify formatCheckType to pass-through - Use stripAnsi/formatDate in get.ts instead of inline regex/formatting

…tive checks - Replace this.exit(1) with process.exitCode = 1 to avoid oclif's global handler printing the error a second time - Exclude inactive checks from --status filter results - Extract filterByStatus() and add unit tests

Add .catch() fallbacks for check-statuses and check-groups API calls so accounts with no checks don't crash with a 404.

Test checks list and get commands against an account with no checks to verify graceful handling of empty responses and 404 fallbacks.

…nfig - Add markdown output branch to showErrorGroupDetail (was rendering terminal/chalk output regardless of --output flag) - Switch empty account e2e tests to use node-config pattern with describe.skipIf for graceful skipping when creds aren't set - Add emptyApiKey/emptyAccountId to e2e config default.js - Document optional empty account test setup in e2e README

MichaelHogers · 2026-02-23T12:27:36Z

checking something with totals not adding up as expected, monitors causing some funniness in the counting

Show per-type counts (e.g. BROWSER: 140 API: 77 ...) on a dim line below the status summary. Filters by activeCheckIds so the subcounts sum to the displayed total.

MichaelHogers · 2026-02-23T14:04:01Z

@sorccu could you give this an initial review please? 🙇

MichaelHogers · 2026-02-23T15:44:29Z

@sorccu what do you typically do with CLI releases? do we best first dogfood these type of changes?

thebiglabasky

I think it's fine, though also believe there could be a case for already centralizing some elements that'll be common across most commands like pagination, command output parameter, or formatting.
The second point is regarding the contract, though I think we could go with this first and refactor later to move the definitions you have there into the contract package.
This made me wonder if by "contract" we wouldn't actually mean a TS SDK that we'd import both from the CLI and webapp and would act as the actual contract against the openapi spec from the BE API.

packages/cli/e2e/__tests__/checks-get.spec.ts

packages/cli/e2e/__tests__/checks-list.spec.ts

packages/cli/src/commands/checks/__tests__/list.spec.ts

packages/cli/src/commands/checks/get.ts

packages/cli/src/formatters/check-result-detail.ts

packages/cli/src/formatters/checks.ts

packages/cli/src/formatters/render.ts

packages/cli/src/rest/check-results.ts

packages/cli/src/rest/checks.ts

MichaelHogers · 2026-02-24T08:11:50Z

thanks @thebiglabasky going through the comments now (on the formatting side i didn't feel super strongly about the code, because it is bound to change and nothing depends directly on that for a while)

MichaelHogers · 2026-02-24T08:19:58Z

I think it's fine, though also believe there could be a case for already centralizing some elements that'll be common across most commands like pagination, command output parameter, or formatting. The second point is regarding the contract, though I think we could go with this first and refactor later to move the definitions you have there into the contract package. This made me wonder if by "contract" we wouldn't actually mean a TS SDK that we'd import both from the CLI and webapp and would act as the actual contract against the openapi spec from the BE API.

@thebiglabasky the way i've done this before is:

backend exports an openapi.json (to me this can be seen as "the contract") - with the versioned header approach these should be permanently stored and named by date* (could sit in the repo)
any client/consumer can turn that openapi.json into a sdk (CLI and webapp likely use different libraries to turn it into their own SDK, e.g. webapp wants a vue friendly one) + i used to have a CI check to ensure webapp uses latest backend openapi.json

*: we need to also build some tooling to check that older contracts still work against latest backend, this could be by validating the contracts directly or simply e2e suits between the range of versions of clients and latest backend, probably former is easiest

thebiglabasky · 2026-02-24T09:57:26Z

any client/consumer can turn that openapi.json into a sdk (CLI and webapp likely use different libraries to turn it into their own SDK, e.g. webapp wants a vue friendly one) + i used to have a CI check to ensure webapp uses latest backend openapi.json

*: we need to also build some tooling to check that older contracts still work against latest backend, this could be by validating the contracts directly or simply e2e suits between the range of versions of clients and latest backend, probably former is easiest

I was thinking this but then wondered why we'd actually bother to separate all these things since it's all TypeScript in the end, so having all the openapi, types and even handy wrapping call methods in a single package suddenly looked appealing to me: so you don't even bother with the API endpoint and structure, it's all typed through the SDK. The openapi part becomes the elements used by the backend and for docs.
I might be naive though, but I'm not sure about the benefits of splitting the Vue consumption from the CLI. Maybe skeletons / streaming or stuff I'm overlooking?

thebiglabasky · 2026-02-24T13:32:21Z

Note for self: came back from the SDK idea, and now sold on sticking to only zod so we can generate the openapi spec, and get runtime validation all in a single place

Replace client-side filtering that fetched all checks (5+ API calls for large accounts) with server-side query params on GET /v1/checks. The command now makes just 2 API calls regardless of filters applied. Remove --status flag (not supported server-side), client-side filter helpers (filterByStatus, buildActiveCheckIds), and their tests.

…nality

Extract shared outputFlag factory to flags.ts. Also improve e2e test assertions per PR review feedback.

oclif auto-discovers all files in the commands directory as commands, causing flags.ts to be registered as checks:flags. Move to src/flags/.

Move flags.ts back to commands/checks/ where it belongs and configure oclif to skip files named flags.* via globPatterns negation.

Revert oclif globPatterns config and move flags.ts to src/helpers/ where it won't interfere with oclif command discovery.

MichaelHogers · 2026-02-25T11:20:56Z

@thebiglabasky finished now with feedback and some improvements

@sorccu could use some pointers on how to do the release now and in the future, sent slack msg as well

thebiglabasky

LGTM!

The --status flag was removed in 372cbe2 when we moved to server-side filtering, but this test was left behind causing CI failures.

MichaelHogers · 2026-02-25T13:15:01Z

I noticed tests are failing — they were still using the --status flag which was removed in 372cbe2 when we moved to server-side filtering. I've cleaned up the failing test in 80ecd78.

otherwise, in a separate agent session I'm looking into adding status filtering to the public API so we can re-enable --status in the CLI as a proper server-side filter, this should be a low complexity change.

TLDR: we can merge this, but i am looking at adding a status filter to our public api endpoint in the meantime, it is quite useful to have

@sorccu i still need some instructions on how we publish our CLI! 🙏

MichaelHogers added 3 commits February 23, 2026 12:02

refactor(cli): move test fixtures to __fixtures__ directory

482d32e

MichaelHogers force-pushed the michael/tim-9-10-11-checks-cli branch from 78aeeb3 to 482d32e Compare February 23, 2026 11:02

MichaelHogers added 6 commits February 23, 2026 12:18

fix(cli): add checks topic to help e2e test expectations

63174a4

fix(cli): avoid leading whitespace in summary bar when no statuses

93dbf06

fix(cli): handle empty account gracefully in checks list

5f03031

Add .catch() fallbacks for check-statuses and check-groups API calls so accounts with no checks don't crash with a 404.

test(cli): add e2e tests for empty account edge cases

95db6bb

Test checks list and get commands against an account with no checks to verify graceful handling of empty responses and 404 fallbacks.

MichaelHogers requested review from sorccu and thebiglabasky February 23, 2026 12:16

feat(cli): add type breakdown line to checks list summary bar

f7c6b16

Show per-type counts (e.g. BROWSER: 140 API: 77 ...) on a dim line below the status summary. Filters by activeCheckIds so the subcounts sum to the displayed total.

thebiglabasky reviewed Feb 23, 2026

View reviewed changes

MichaelHogers added 9 commits February 24, 2026 16:26

fix(cli): update e2e test expectation for checks output format

771423e

test(cli): enhance e2e tests for checks list output and limit functio…

bd84adc

…nality

refactor(cli): centralize output flag for checks commands

2aadd76

Extract shared outputFlag factory to flags.ts. Also improve e2e test assertions per PR review feedback.

fix(cli): move shared flags out of commands directory

81fb682

oclif auto-discovers all files in the commands directory as commands, causing flags.ts to be registered as checks:flags. Move to src/flags/.

Merge branch 'main' into michael/tim-9-10-11-checks-cli

3c66ad8

fix(cli): use oclif globPatterns to exclude flags from command discovery

60856d2

Move flags.ts back to commands/checks/ where it belongs and configure oclif to skip files named flags.* via globPatterns negation.

fix(cli): narrow oclif glob exclusion to checks/flags only

e25c652

refactor(cli): prefix shared flags file with underscore convention

ed903bf

MichaelHogers added 2 commits February 25, 2026 12:14

fix(cli): remove TS extensions from oclif globPatterns

20d75e3

refactor(cli): move shared flags to helpers directory

763fae8

Revert oclif globPatterns config and move flags.ts to src/helpers/ where it won't interfere with oclif command discovery.

thebiglabasky previously approved these changes Feb 25, 2026

View reviewed changes

test(cli): remove --status flag e2e test

80ecd78

The --status flag was removed in 372cbe2 when we moved to server-side filtering, but this test was left behind causing CI failures.

MichaelHogers dismissed thebiglabasky’s stale review via 80ecd78 February 25, 2026 13:11

thebiglabasky approved these changes Feb 25, 2026

View reviewed changes

MichaelHogers merged commit 048b121 into main Feb 25, 2026
7 of 8 checks passed

MichaelHogers deleted the michael/tim-9-10-11-checks-cli branch February 25, 2026 15:19

Conversation

MichaelHogers commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

MichaelHogers commented Feb 23, 2026

Uh oh!

MichaelHogers commented Feb 23, 2026

Uh oh!

MichaelHogers commented Feb 23, 2026

Uh oh!

thebiglabasky left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MichaelHogers commented Feb 24, 2026

Uh oh!

MichaelHogers commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thebiglabasky commented Feb 24, 2026

Uh oh!

thebiglabasky commented Feb 24, 2026

Uh oh!

MichaelHogers commented Feb 25, 2026

Uh oh!

thebiglabasky left a comment

Choose a reason for hiding this comment

Uh oh!

MichaelHogers commented Feb 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MichaelHogers commented Feb 23, 2026 •

edited

Loading

MichaelHogers commented Feb 24, 2026 •

edited

Loading