checkly test-sessions

Inspect recorded test sessions and their error groups.

Available since CLI v8.4.0.

The checkly test-sessions command lets you inspect recorded test sessions from the terminal. Use it to list recent sessions, review a session, wait for a running session to finish, or inspect a test session error group before starting root cause analysis.

Prerequisites

Before using checkly test-sessions, ensure you have:

• Checkly CLI installed
• Valid Checkly account authentication (run npx checkly login if needed)
• A recorded test session ID

For additional setup information, see CLI overview.

Usage

Terminal

npx checkly test-sessions <subcommand> [arguments] [options]

Subcommands

Subcommand	Description
list	List recorded test sessions.
get	Get details of a recorded test session.

checkly test-sessions list

The checkly test-sessions list command is only available since CLI v8.5.0.

List recorded test sessions for the currently selected account. Use filters to narrow by status, branch, user, or provider, and cursor pagination to page through results.

Usage:

Terminal

npx checkly test-sessions list [options]

Options:

Option	Required	Description
--limit, -l	-	Number of test sessions to return (1-100). Default: 20.
--cursor	-	Cursor for the next page (from previous output).
--from	-	Only include test sessions created at or after this ISO date or Unix timestamp.
--to	-	Only include test sessions created before this ISO date or Unix timestamp.
--status	-	Filter by status: running, failed, passed, or cancelled. Can be specified multiple times.
--branch	-	Filter by Git branch name. Can be specified multiple times.
--user	-	Filter by commit owner or invoking user ID. Can be specified multiple times.
--no-users	-	Include sessions with no commit owner and no invoking user.
--provider	-	Filter by provider: github, vercel, api, trigger, or pw_reporter. Can be specified multiple times.
--search, -s	-	Search test session text fields (3-200 characters).
--error-group	-	Filter by test-session error group ID.
--output, -o	-	Output format: table, json, or md. Default: table.

List Options

--limit, -l · number · default: "20"

Number of test sessions to return, between 1 and 100.

Usage:

Terminal

npx checkly test-sessions list --limit=50
npx checkly test-sessions list -l 10

--cursor · string

Cursor for paginating through results. Use the cursor value from the previous output, or the next-page command shown in table output.

Usage:

Terminal

npx checkly test-sessions list --limit=20 --cursor=<cursor>

--from · string

Only include test sessions created at or after this point in time. Accepts an ISO date (such as 2026-06-01) or a Unix timestamp in seconds.

Usage:

Terminal

npx checkly test-sessions list --from=2026-06-01

--to · string

Only include test sessions created before this point in time. Accepts an ISO date or a Unix timestamp in seconds.

Usage:

Terminal

npx checkly test-sessions list --from=2026-06-01 --to=2026-06-15

--status · string

Filter sessions by status. Available values: running, failed, passed, cancelled. Specify multiple times to match more than one status.

Usage:

Terminal

npx checkly test-sessions list --status=failed
npx checkly test-sessions list --status=failed --status=running

--branch · string

Filter sessions by Git branch name. Specify multiple times to match more than one branch.

Usage:

Terminal

npx checkly test-sessions list --branch=main
npx checkly test-sessions list --branch=main --branch=staging

--user · string

Filter sessions by commit owner or invoking user ID. Specify multiple times to match more than one user.

Usage:

Terminal

npx checkly test-sessions list --user=<user-id>

--no-users · boolean

Include sessions that have no commit owner and no invoking user.

Usage:

Terminal

npx checkly test-sessions list --no-users

--provider · string

Filter sessions by the provider that triggered them. Available values: github, vercel, api, trigger, pw_reporter. Specify multiple times to match more than one provider.

Usage:

Terminal

npx checkly test-sessions list --provider=github
npx checkly test-sessions list --provider=trigger --provider=api

--search, -s · string

Search test session text fields. The query must be between 3 and 200 characters.

Usage:

Terminal

npx checkly test-sessions list --search="checkout flow"
npx checkly test-sessions list -s "homepage"

--error-group · string

Filter sessions by a test-session error group ID.

Usage:

Terminal

npx checkly test-sessions list --error-group=<error-group-id>

--output, -o · string · default: "table"

Set the output format. Use json for programmatic access or md for markdown.

Usage:

Terminal

npx checkly test-sessions list --output=json
npx checkly test-sessions list -o md

List Examples

Terminal

# List recent test sessions
npx checkly test-sessions list

# Show only failed sessions
npx checkly test-sessions list --status=failed

# Filter by branch and provider
npx checkly test-sessions list --branch=main --provider=github

# Filter by a time range
npx checkly test-sessions list --from=2026-06-01 --to=2026-06-15

# Get results as JSON
npx checkly test-sessions list --output=json

# Page through results
npx checkly test-sessions list --limit=20 --cursor=<cursor>

checkly test-sessions get

Get details of a recorded test session, including result error groups for RCA.

Usage:

Terminal

npx checkly test-sessions get <id> [options]

Arguments:

Argument	Description
id	The ID of the test session to retrieve.

Options:

Option	Required	Description
--result, -r	-	Show details for a specific test session result ID.
--error-group	-	Show details for a test session error group ID from this session.
--error-groups-limit	-	Number of error group IDs to show in the session summary. Default: 5.
--full-error	-	Print the complete raw error when showing a test session error group.
--watch, -w	-	Watch a running test session until it completes before rendering.
--output, -o	-	Output format: detail, json, or md. Default: detail.

Get Options

--result, -r · string

Available in CLI v8.7.0+.

Drill into a specific test session result by its result ID. Shows detailed information for that result, including logs and timing data.

Usage:

Terminal

npx checkly test-sessions get <id> --result=<result-id>
npx checkly test-sessions get <id> -r <result-id>

--error-group · string

Show details for a test session error group from the selected session. Use this after the session summary shows one or more error group IDs.

Usage:

Terminal

npx checkly test-sessions get <id> --error-group=<error-group-id>

--error-groups-limit · number · default: "5"

Set how many error group IDs to show in the session summary.

Usage:

Terminal

npx checkly test-sessions get <id> --error-groups-limit=10

--full-error · boolean · default: "false"

Print the complete raw error when you inspect a test session error group.

Usage:

Terminal

npx checkly test-sessions get <id> --error-group=<error-group-id> --full-error

--watch, -w · boolean · default: "false"

Available in CLI v8.5.0+.

Watch a running test session until it reaches a final state before rendering the result.

Usage:

Terminal

npx checkly test-sessions get <id> --watch
npx checkly test-sessions get <id> -w

--output, -o · string · default: "detail"

Set the output format. Use json for programmatic access or md for markdown.

Usage:

Terminal

npx checkly test-sessions get <id> --output=json
npx checkly test-sessions get <id> -o md

Get Examples

Terminal

# View a recorded test session
npx checkly test-sessions get <id>

# Wait for a running test session to complete
npx checkly test-sessions get <id> --watch

# Drill into a specific result
npx checkly test-sessions get <id> --result=<result-id>

# Inspect a test session error group
npx checkly test-sessions get <id> --error-group=<error-group-id>

# Get the session as JSON
npx checkly test-sessions get <id> --output=json

Related Commands

• checkly trigger - Trigger deployed checks as a test session
• checkly test - Test local checks as a test session
• checkly rca - Trigger root cause analysis for error groups
• checkly assets - List and download result assets from a test session