Skip to main content
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.
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

SubcommandDescription
listList recorded test sessions.
getGet 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:
OptionRequiredDescription
--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:
ArgumentDescription
idThe ID of the test session to retrieve.
Options:
OptionRequiredDescription
--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