> ## Documentation Index
> Fetch the complete documentation index at: https://checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# checkly trigger
> Trigger checks already in your Checkly account.
export const command_0 = "checkly trigger"
The `checkly trigger` command executes checks that are already deployed in your Checkly account as [a test session](/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.
Before using {command_0}, 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](/cli/overview).
## Usage
The basic command triggers all checks in your account that are already deployed.
```bash Terminal theme={null}
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 checks to complete. |
| `--verbose, -v` | - | Always show the full logs of the checks. |
## Command Options
Specify a configuration file to use instead of the `checkly.config.ts` or `checkly.config.js` in the current directory.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --config checkly.config.ts
npx checkly trigger -c="./checkly.staging.config.ts"
```
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:**
```bash Terminal theme={null}
npx checkly trigger --check-id=
npx checkly trigger --check-id=,
npx checkly trigger --check-id= --check-id=
```
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:**
```bash Terminal theme={null}
npx checkly trigger --detach
```
[Environment variables](/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:**
```bash Terminal theme={null}
npx checkly trigger --env KEY=value
npx checkly trigger -e KEY=value
```
**Examples:**
```bash Terminal theme={null}
# 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
```
Path to a dotenv file containing environment variables.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --env-file=".env"
npx checkly trigger -e=".env"
```
**Examples:**
```bash Terminal theme={null}
# 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.
The location to run the checks at.
**Usage:**
```bash Terminal theme={null}
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.
The private location to run checks at.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --private-location="my-private-location"
```
**Examples:**
```bash Terminal theme={null}
# 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.
Filter checks using tags. Checks run if they contain all specified tags in a single --tags flag. Multiple --tags flags create OR conditions.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --tags="tag1,tag2"
npx checkly trigger -t="tag1,tag2"
```
**Examples:**
```bash Terminal theme={null}
# 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.
A name to use when recording results in Checkly.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --test-session-name="Custom session name"
```
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:**
```bash Terminal theme={null}
npx checkly trigger --reporter list
npx checkly trigger -r list
```
**Examples:**
```bash Terminal theme={null}
# 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
```
Always show the full logs of the checks.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --verbose
npx checkly trigger -v
```
Exit with a failing status code when there are no matching tests.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --fail-on-no-matching
npx checkly trigger --no-fail-on-no-matching
```
**Examples:**
```bash Terminal theme={null}
# 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.
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:**
```bash Terminal theme={null}
npx checkly trigger
npx checkly trigger --no-record
```
**Examples:**
```bash Terminal theme={null}
# 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.
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:**
```bash Terminal theme={null}
npx checkly trigger --refresh-cache
```
How many times to retry a failed check run.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --retries="2"
```
**Examples:**
```bash Terminal theme={null}
# 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.
Timeout in seconds to wait for checks to complete.
**Usage:**
```bash Terminal theme={null}
npx checkly trigger --timeout 300
```
**Examples:**
```bash Terminal theme={null}
# 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:
```bash Terminal theme={null}
npx checkly trigger --tags staging --test-session-name "Pre-prod validation"
```
If your production deployment includes monitoring changes and updates, [use `npx checkly test`](/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](/concepts/cancellation) for the full flow.
## Related Commands
* [`checkly deploy`](/cli/checkly-deploy) - Deploy your Checkly configuration
* [`checkly test`](/cli/checkly-test) - Test your setup before deployment