The checkly trigger command executes checks that are already deployed in your Checkly account. 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 , 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.

​
Usage

The basic command triggers all checks in your account that are already deployed.
Terminal
npx checkly trigger [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 check run. Default: empty. Multiple values can be passed.
--env-filedotenv file path to be passed. For example --env-file="./.env"
--fail-on-no-matchingExit with a failing status code when there are no matching tests.
--location, -lThe location to run the checks at.
--private-locationThe private location to run checks at.
--recordRecord check 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 check 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.
--verbose, -vAlways show the full logs of the checks.

​
Command Options

​
--config
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"
​
--env
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
​
--env-file
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.
​
--location
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.
​
--private-location
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.
​
--tags
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.
​
--test-session-name
string
A name to use when storing results in Checkly with --record.Usage:
Terminal
npx checkly trigger --record --test-session-name="Custom session name"
​
--reporter
string
Custom reporters for test output formatting.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
Available options: list, dot, ci, github, json. Each provides different output formatting.
​
--verbose
boolean
Always show the full logs of the checks.Usage:
Terminal
npx checkly trigger --verbose
npx checkly trigger -v
​
--fail-on-no-matching
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.
​
--record
boolean
Record check results in Checkly as a test session with full logs, traces and videos.Usage:
Terminal
npx checkly trigger --record
Examples:
Terminal
# Basic recording
npx checkly trigger --record

# Record with custom name
npx checkly trigger --record --test-session-name "Deploy validation"

# Record specific checks
npx checkly trigger --record --tags critical
Records provide full visibility including logs, traces, and videos for debugging failed checks.
​
--retries
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.
​
--timeout
number
default:"600"
Timeout in seconds to wait for checks to complete.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:
Featurecheckly testcheckly trigger
SourceLocal project filesDeployed checks in account
File patternsSupports file matchingNot applicable
Check creationCan run checks from codeUses existing checks only
SnapshotsCan update snapshotsCannot update snapshots
DependenciesRequires local projectWorks independently

​
Use Cases

​
Pre-deployment Validation

Run your deployed checks before promoting code to production:
Terminal
npx checkly trigger --tags staging --record --test-session-name "Pre-prod validation"
If your production deployment includes monitoring changes and updates, use npx checkly test to validate your preview environment with the updated monitoring configuration.