# checkly trigger - Checkly Docs

> Trigger checks already in your Checkly account.

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

---

- Usage
- Command Options
- Key Differences from checkly test
- Use Cases Pre-deployment Validation

- Cancelling a run
- Related Commands

CLI Commands

# checkly trigger

Trigger checks already in your Checkly account.

The `checkly trigger` command executes checks that are already deployed in your Checkly account as [a test session](https://www.checklyhq.com/docs/detect/testing/overview). Unlike the `test` command, `trigger` works with any checks in your account regardless of how they were created - via CLI constructs, the web UI, or Terraform.

Prerequisites

Before using `checkly trigger`, 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).

## ​ Usage

The basic command triggers all checks in your account that are already deployed.
Terminal

```
npx checkly trigger [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.

`--check-id` - Trigger specific checks by ID. Supports comma-separated values and repeated flags.

`--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 check run. Default: empty. Multiple values can be passed.

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

`--fail-on-no-matching` - Exit with a failing status code when there are no matching tests.

`--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 check 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.

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

## ​ Command Options

​

string

Specify a configuration file to use instead of the `checkly.config.ts` or `checkly.config.js` in the current directory. **Usage:** Terminal

```
npx checkly trigger --config checkly.config.ts
npx checkly trigger -c="./checkly.staging.config.ts"
```

​

string[]

Available since CLI v8.4.0.

Trigger specific checks by ID. You can pass a comma-separated list or repeat the flag. Combine `--check-id` with `--tags` to further filter the matching checks. **Usage:** Terminal

```
npx checkly trigger --check-id=
npx checkly trigger --check-id= ,
npx checkly trigger --check-id= --check-id=
```

​

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 trigger --detach
```

​

string[]

[Environment variables](https://www.checklyhq.com/docs/cli/environment-variables) to be passed to the check run. Multiple values can be passed and passed variables overwrite any existing variables stored in your Checkly account. **Usage:** Terminal

```
npx checkly trigger --env KEY=value
npx checkly trigger -e KEY=value
```

**Examples:** Terminal

```
# Single environment variable
npx checkly trigger --env ENVIRONMENT_URL="https://staging.acme.com"

# Multiple environment variables
npx checkly trigger --env API_URL=https://api.example.com --env API_KEY=secret123
```

​

string

Path to a dotenv file containing environment variables. **Usage:** Terminal

```
npx checkly trigger --env-file=".env"
npx checkly trigger -e=".env"
```

**Examples:** Terminal

```
# Use default .env file
npx checkly trigger --env-file=".env"

# Use environment-specific file
npx checkly trigger --env-file=".env.production"

# Use file from different directory
npx checkly trigger --env-file="./config/.env.staging"
```

The dotenv file should contain KEY=value pairs, one per line.

​

string

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

```
npx checkly trigger --location="us-east-1"
npx checkly trigger -l="us-east-1"
```

Choose from available Checkly public locations like us-east-1, eu-west-1, ap-southeast-1, etc.

​

string

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

```
npx checkly trigger --private-location="my-private-location"
```

**Examples:** Terminal

```
# Use private location
npx checkly trigger --private-location="datacenter-1"

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

# With custom config
npx checkly trigger --private-location"vpc-location" --config="internal.config.js"
```

Private locations must be configured in your Checkly account before use.

​

string[]

Filter checks using tags. Checks run if they contain all specified tags in a single —tags flag. Multiple —tags flags create OR conditions. **Usage:** Terminal

```
npx checkly trigger --tags="tag1,tag2"
npx checkly trigger -t="tag1,tag2"
```

**Examples:** Terminal

```
# Single tag
npx checkly trigger --tags="production"

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

# Multiple tag groups (OR condition)
npx checkly trigger --tags="production,webapp" --tags="production,backend"
# Runs checks with (production AND webapp) OR (production AND backend)
```

Tags are comma-separated within a single flag for AND logic, multiple flags for OR logic.

​

string

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

```
npx checkly trigger --test-session-name="Custom session name"
```

​

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. **Usage:** Terminal

```
npx checkly trigger --reporter list
npx checkly trigger -r list
```

**Examples:** Terminal

```
# List reporter (default)
npx checkly trigger --reporter list

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

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

# GitHub Actions reporter
npx checkly trigger --reporter github

# JSON output for programmatic use
npx checkly trigger --reporter json > results.json

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

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

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

​

boolean

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

```
npx checkly trigger --verbose
npx checkly trigger -v
```

​

boolean

Exit with a failing status code when there are no matching tests. **Usage:** Terminal

```
npx checkly trigger --fail-on-no-matching
npx checkly trigger --no-fail-on-no-matching
```

**Examples:** Terminal

```
# Default behavior (enabled)
npx checkly trigger --tags non-existent-tag
# Exits with error if no checks match

# Disable the behavior
npx checkly trigger --no-fail-on-no-matching --tags optional-tag
# Exits successfully even if no checks match
```

Enabled by default. Use `--no-fail-on-no-matching` to allow zero matches without failure.

​

boolean

default: "true"

Record check results in Checkly as a test session 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 trigger
npx checkly trigger --no-record
```

**Examples:** Terminal

```
# Run with a custom session name
npx checkly trigger --test-session-name "Deploy validation"

# Run specific checks
npx checkly trigger --tags critical

# Run selected checks by ID
npx checkly trigger --check-id=

# Run without recording
npx checkly trigger --no-record
```

Records provide full visibility including logs, traces, and videos for debugging failed checks.

​

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 trigger --refresh-cache
```

​

number

default: "0"

How many times to retry a failed check run. **Usage:** Terminal

```
npx checkly trigger --retries="2"
```

**Examples:** Terminal

```
# No retries (default)
npx checkly trigger --retries 0

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

# Maximum retries
npx checkly trigger --retries 3
```

Default: 0, Maximum: 3. Useful for handling transient failures.

​

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 trigger --timeout 300
```

**Examples:** Terminal

```
# Quick timeout for fast checks
npx checkly trigger --timeout 60

# Default timeout
npx checkly trigger --timeout 600

# Extended timeout for slow checks
npx checkly trigger --timeout 1200
```

Default: 600 seconds (10 minutes). Adjust based on your longest-running checks.

## ​ Key Differences from `checkly test`

`npx checkly test` and `npx checkly trigger` serve different purposes in the Checkly ecosystem. Here’s a comparison of their key features:
Feature `checkly test` `checkly trigger`

**Source** Local project files Deployed checks in account

**File patterns** Supports file matching Not applicable

**Check creation** Can run checks from code Uses existing checks only

**Snapshots** Can update snapshots Cannot update snapshots

**Dependencies** Requires local project Works independently

## ​ Use Cases

### ​ Pre-deployment Validation

Run your deployed checks before promoting code to production:
Terminal

```
npx checkly trigger --tags staging --test-session-name "Pre-prod validation"
```

If your production deployment includes monitoring changes and updates, [use `npx checkly test`](https://www.checklyhq.com/docs/cli/checkly-test) to validate your preview environment with the updated monitoring configuration.

## ​ Cancelling a run

Available in CLI v8.0.0+.

`checkly trigger` 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 deploy`](https://www.checklyhq.com/docs/cli/checkly-deploy) - Deploy your Checkly configuration

- [`checkly test`](https://www.checklyhq.com/docs/cli/checkly-test) - Test your setup before deployment

Was this page helpful?

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

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

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