The checkly test command executes all checks in your project on the Checkly cloud infrastructure. This command provides a dry-run capability for testing your monitoring setup before deployment, with support for different environments and configurations.
Before using , ensure you have:
  • An initialized Checkly CLI project
  • At least one check or resource defined in your project
  • Valid Checkly account authentication (run npx checkly login if needed)
  • A checkly.config.ts or checkly.config.js configuration file
For additional setup information, see CLI overview.

​
Basic Usage

The basic command runs all checks in your project as a test run without deploying them to your account as monitors.
Terminal
npx checkly test [arguments] [options]
OptionDescription
--config, -cThe Checkly CLI configuration file. If not passed, uses the checkly.config.ts|js file in the current directory.
--env, -eEnv vars to be passed to the test run. Can be used multiple times.
--env-filedotenv file path to be passed. For example --env-file="./.env"
--grep, -gOnly run checks where the check name matches a regular expression. Default: .*
--listList all checks but don’t run them.
--location, -lThe location to run the checks at.
--private-locationThe private location to run checks at.
--recordRecord test results in Checkly as a test session with full logs, traces and videos.
--reporter, -rA list of custom reporters for the test output.
--retriesHow many times to retry a failing test run.
--tags, -tFilter the checks to be run using a comma separated list of tags.
--test-session-name, -nA name to use when storing results in Checkly with --record.
--timeoutA timeout (in seconds) to wait for checks to complete.
--update-snapshots, -uUpdate any snapshots using the actual result of this test run.
--verbose, -vAlways show the full logs of the checks.
--[no-]verify-runtime-dependenciesReturn an error if checks import dependencies that are not supported by the selected runtime.

​
Command Options

​
--config
string
The Checkly CLI configuration file. If not passed, uses the checkly.config.ts|js file in the current directory.Usage:
Terminal
npx checkly test --config="./checkly.staging.config.ts"
npx checkly test -c="./checkly.staging.config.ts"
​
--env
string[]
Environment variables to be passed to the test run. Can be used multiple times.Usage:
Terminal
npx checkly test --env KEY=value
npx checkly test -e KEY=value
Examples:
Terminal
# Single environment variable
npx checkly test --env "API_KEY=123456"

# Multiple environment variables
npx checkly test --env "API_KEY=123456" --env "BASE_URL=https://api.example.com"
​
--env-file
string
Path to a dotenv file containing environment variables.Usage:
Terminal
npx checkly test --env-file="./.env"
npx checkly test --env-file="./config/.env.production"
​
--grep
string
Only run checks where the check name matches a regular expression. Default: .*Usage:
Terminal
npx checkly test --grep="api-.*"
npx checkly test -g="^production-.*"
​
--location
string
The location to run the checks at.Usage:
Terminal
npx checkly test --location="us-east-1"
npx checkly test -l="eu-west-1"
​
--private-location
string
The private location to run checks at.Usage:
Terminal
npx checkly test --private-location="my-private-location"
Examples:
Terminal
# Use private location
npx checkly test --private-location="datacenter-1"

# Combine with tags
npx checkly test --private-location="office-network" --tags="internal"

# With custom config
npx checkly test --private-location="office-network" --config="./checkly.office.config.ts"
​
--tags
string[]
Filter the checks to be run using a comma separated list of tags. Checks will only be run if they contain all of the specified tags. Multiple --tags flags can be passed, in which case checks will be run if they match any of the --tags filters.Usage:
Terminal
npx checkly test --tags="tag1,tag2"
npx checkly test -t="tag1,tag2"
Examples:
Terminal
# Single tag
npx checkly test --tags="production"

# Multiple tags (AND condition)
npx checkly test --tags="production,webapp"

# Multiple tag groups (OR condition)
npx checkly test --tags="critical,api" --tags="critical,ui"
# Runs checks with (critical AND api) OR (critical AND ui)
​
--list
boolean
List all checks to be run but don’t run them.Usage:
Terminal
# List checks
npx checkly test --list

# List checks with `api-` in the name
npx checkly test --list --grep="api-.*"

# List checks with the `production` tag
npx checkly test --list --tags="production"
​
--reporter
string
A list of custom reporters for the test output. Options: list|dot|ci|github|jsonUsage:
Terminal
npx checkly test --reporter=list
npx checkly test -r=list
Examples:
Terminal
# List reporter (default)
npx checkly test --reporter list

# Dot reporter for minimal output
npx checkly test --reporter dot

# CI-optimized reporter
npx checkly test --reporter ci

# GitHub Actions reporter
npx checkly test --reporter github

# JSON output for programmatic use
npx checkly test --reporter json > results.json
​
--record
boolean
Record test results in Checkly as a test session with full logs, traces and videos.Usage:
Terminal
npx checkly test --record
npx checkly test --record --test-session-name="CI Build #123"
​
--retries
number
How many times to retry a failing test run. Default: 0, max: 3Usage:
Terminal
npx checkly test --retries=2
Examples:
Terminal
# No retries (default)
npx checkly test --retries 0

# Retry twice on failure
npx checkly test --retries 2

# Maximum retries
npx checkly test --retries 3
​
--test-session-name
string
A name to use when storing results in Checkly with --record.Usage:
Terminal
npx checkly test --record --test-session-name="Release v1.2.3"
npx checkly test --record -n="Nightly Test Run"
​
--timeout
number
default:"600"
A timeout (in seconds) to wait for checks to complete.Usage:
Terminal
npx checkly test --timeout=300
​
--update-snapshots
boolean
Update any snapshots using the actual result of this test run.Usage:
Terminal
npx checkly test --update-snapshots
npx checkly test -u
Snapshots are essential for visual regression testing in Browser Checks.
​
--verbose
boolean
Always show the full logs of the checks.Usage:
Terminal
npx checkly test --verbose
npx checkly test -v
​
--verify-runtime-dependencies
boolean
Return an error if checks import dependencies that are not supported by the selected runtime. Default: trueUsage:
Terminal
npx checkly test --verify-runtime-dependencies
npx checkly test --no-verify-runtime-dependencies
Runtime-dependent checks run in a specific runtime with a pre-defined set of dependencies. If you’re using private locations and want to provide your own dependencies, disable the built-in dependency validation.
You can provide custom dependencies in Playwright Check Suites because they don’t rely on a specific runtime.

​
Examples

Dry run all your project checks and monitors:
Terminal
npx checkly test
Dry run checks that have product and api in the file name:
Terminal
npx checkly test product api
Record a test session in Checkly with git branch info, full logging, videos and traces:
Terminal
npx checkly test --record
Dry run all checks against a specific location:
Terminal
npx checkly test --location eu-west-1
Specify environment variables to dry run checks with a specific URL and a password. These variables are available on process.env:
Terminal
npx checkly test --env ENVIRONMENT_URL="https://preview.acme.com" --env PASSWORD=doremiabc123