# checkly test - Checkly Docs

> Run checks in your project using the Checkly CLI.

Source: https://www.checklyhq.com/docs/cli/checkly-test/

---

- Basic Usage
- Command Options
- Examples
- Cancelling a run
- Related Commands

CLI Commands

# checkly test

Run checks in your project using the Checkly CLI.

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.

Prerequisites

Before using `checkly test`, 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](https://www.checklyhq.com/docs/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]
```

Option Required Description

`--config, -c` - The Checkly CLI configuration file. If not passed, uses the `checkly.config.ts|js` file in the current directory.

`--detach, -d` - Keep checks running in the cloud when you stop the CLI with Ctrl+C, instead of cancelling the run.

`--env, -e` - Env vars to be passed to the test run. Can be used multiple times.

`--env-file` - dotenv file path to be passed. For example `--env-file="./.env"`

`--grep, -g` - Only run checks where the check name matches a regular expression. Default: `.*`

`--list` - List all checks but don’t run them.

`--location, -l` - The location to run the checks at.

`--private-location` - The private location to run checks at.

`--[no-]record` - Record test session results in Checkly with full logs, traces and videos. Records by default since CLI v8.0.0.

`--refresh-cache` - Force a fresh install of dependencies and update the cached version.

`--reporter, -r` - One or more custom reporters for the test output. Supports comma-separated values and repeated flags.

`--retries` - How many times to retry a failing test run.

`--tags, -t` - Filter the checks to be run using a comma separated list of tags.

`--test-session-name, -n` - A name to use when recording results in Checkly.

`--timeout` - A timeout (in seconds) to wait for each check to make progress once it starts running: report a retry attempt or its result. Checks that have not started yet get up to 900 additional seconds for server-side scheduling.

`--update-snapshots, -u` - Update any snapshots using the actual result of this test run.

`--verbose, -v` - Always show the full logs of the checks.

`--[no-]verify-runtime-dependencies` - Return an error if checks import dependencies that are not supported by the selected runtime.

## ​ Command Options

​

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

​

boolean

default: "false"

By default, pressing Ctrl + C during a recorded run cancels the test session. With `--detach`, Ctrl + C exits the CLI immediately instead, leaving the checks running in the cloud. **Usage:** Terminal

```
npx checkly test --detach
```

​

string[]

[Environment variables](https://www.checklyhq.com/docs/cli/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"
```

​

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

​

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-.*"
```

​

string

The location to run the checks at. **Usage:** Terminal

```
npx checkly test --location="us-east-1"
npx checkly test -l="eu-west-1"
```

​

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

​

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

​

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

​

string[]

One or more custom reporters for the test output. Options: `list`, `dot`, `ci`, `github`, `json`. You can combine multiple reporters by passing multiple `--reporter` flags or using a comma-separated list. When no `--reporter` flag is provided, the CLI falls back to the `cli.reporters` array in `checkly.config.ts`, then defaults to `list` (or `ci` in CI environments). **Usage:** 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

# Multiple reporters using comma-separated values
npx checkly test --reporter list,json

# Multiple reporters using repeated flags
npx checkly test --reporter list --reporter json

# Short form with multiple reporters
npx checkly test -r github -r json
```

​

boolean

default: "true"

Record test results in Checkly as [a test session](https://www.checklyhq.com/docs/detect/testing/overview) with full logs, traces and videos. Recording is enabled by default; use `--no-record` to disable it.

Recording defaults to enabled since CLI v8.0.0. In earlier versions, recording was opt-in via `--record`.

**Usage:** Terminal

```
npx checkly test
npx checkly test --no-record
npx checkly test --test-session-name="CI Build #123"
```

​

boolean

default: "false"

Force a fresh install of dependencies and update the cached version. Use this when you’ve changed your project’s dependencies and need Checkly to pick up the latest versions instead of using the cache from a previous run. **Usage:** Terminal

```
npx checkly test --refresh-cache
```

​

number

How many times to retry a failing test run. Default: 0, max: 3 A check that passes after one or more retries still counts as passed, but the output shows how many retries it needed, for example `(2 retries)`, and the summary counts it as flaky. **Usage:** 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
```

​

string

A name to use when recording results in Checkly. **Usage:** Terminal

```
npx checkly test --test-session-name="Release v1.2.3"
npx checkly test -n="Nightly Test Run"
```

​

number

default: "600"

A timeout (in seconds) to wait for each check to make progress once it starts running: report a retry attempt or its result. Checks that have not started yet get up to 900 additional seconds for server-side scheduling. The timer restarts whenever a check starts running and whenever it reports a failed attempt that will be retried, so a check that retries several times can take longer than this value in total. The timeout only ends the wait when a check stops reporting progress. Checkly can stagger the start of checks in large test sessions by up to 900 seconds. If a check still has not started within this value plus that allowance, the CLI reports that the check did not start. That usually means a problem on Checkly’s side: check [the status page](https://is.checkly.online/) or contact support. **Usage:** Terminal

```
npx checkly test --timeout=300
```

​

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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/visual-regressions).

​

boolean

Always show the full logs of the checks. **Usage:** Terminal

```
npx checkly test --verbose
npx checkly test -v
```

​

boolean

Return an error if checks import dependencies that are not supported by the selected runtime. Default: true **Usage:** 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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/overview) 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
```

Run a test session in Checkly with git branch info, full logging, videos and traces:
Terminal

```
npx checkly test
```

Dry run all checks against a specific location:
Terminal

```
npx checkly test --location eu-west-1
```

Specify [environment variables](https://www.checklyhq.com/docs/cli/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
```

## ​ Cancelling a run

Available in CLI v8.0.0+.

`checkly test` records a test session by default, so pressing Ctrl + C cancels it. Cancellation applies only to Playwright Check Suite runs inside the session; other check types finish normally. Runs started with `--no-record` cannot be cancelled.
The CLI keeps running after the first Ctrl + C to report the cancelled results. Press Ctrl + C again to exit immediately without waiting.
Pass the `--detach` flag to keep the checks running in the cloud instead — Ctrl + C then exits the CLI immediately without cancelling.
See [Cancellation](https://www.checklyhq.com/docs/concepts/cancellation) for the full flow.

## ​ Related Commands

- [`checkly pw-test`](https://www.checklyhq.com/docs/cli/checkly-pw-test) - Run Playwright tests in the Checkly cloud

- [`checkly trigger`](https://www.checklyhq.com/docs/cli/checkly-trigger) - Run deployed checks on-demand

- [`checkly deploy`](https://www.checklyhq.com/docs/cli/checkly-deploy) - Deploy your application

Was this page helpful?

[Suggest edits](https://github.com/checkly/docs/edit/main/cli/checkly-test.mdx)[Raise issue](https://github.com/checkly/docs/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/checkly-test)

[checkly sync-playwright Previous](https://www.checklyhq.com/docs/cli/checkly-sync-playwright)[checkly test-sessions Next](https://www.checklyhq.com/docs/cli/checkly-test-sessions)

[x](https://x.com/checklyhq)[github](https://github.com/checkly)[linkedin](https://linkedin.com/company/checkly)

[Powered by This documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=checkly-422f444a)