checkly deploy

Deploy checks and resources to your Checkly account.

The checkly deploy command deploys all your checks and associated resources like alert channels to your Checkly account. This command synchronizes your local monitoring-as-code configuration with your Checkly account.

Prerequisites

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 deploys all resources to your Checkly account, synchronizing your local monitoring-as-code configuration with the Checkly monitoring infrastructure.

Terminal

npx checkly deploy [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.
--force, -f	-	Force mode. Skips the confirmation dialog.
--debug-bundle	-	Generate a JSON file containing the data sent to our servers when you deploy. Note: This flag is in beta. The bundle’s structure is not considered a stable format and may change without notice. It’s intended for one-off troubleshooting, and note it may contain secrets before sharing.
--output, -o	-	Show the changes made after the deploy command.
--preview, -p	-	Show a preview of the changes made by the deploy command.
--preserve-resources	-	Detach resources removed from code (keeping them and their run history) instead of deleting them.
--[no-]schedule-on-deploy	-	Enables automatic check scheduling after a deploy.
--[no-]verify-runtime-dependencies	-	Return an error if checks import dependencies that are not supported by the selected runtime.

Command Options

--config, -c · 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 deploy --config="./checkly.staging.config.ts"
npx checkly deploy -c="./checkly.staging.config.ts"

--force, -f · boolean

Skip the interactive confirmation dialog and proceed with the operation.

Use --force to set up automated CI/CD pipelines testing preview environments and deploying monitoring changes automatically.

Usage:

Terminal

npx checkly deploy --force
npx checkly deploy -f

Examples

Terminal

$ npx checkly deploy --force

Parsing your project... ✅
Validating project resources... ✅
Bundling project resources... ✅

Successfully deployed project "Website Monitoring" to account "Monitoring as Code".

--output, -o · boolean

Show applied differences after deploying, providing a summary of what was changed.

Usage:

Terminal

npx checkly deploy --output
npx checkly deploy -o

Examples:

Terminal

$ npx checkly deploy --output --force

Parsing your project... ✅
Validating project resources... ✅
Bundling project resources... ✅

Create:
  UrlMonitor:: homepage-uptime
  MultiStepCheck: auth-api-flow

Delete:
  Check: legacy-api-check

Update and Unchanged:
  SmsAlertChannel: sms-channel-1

Successfully deployed project "Website Monitoring" to account "Monitoring as Code".

--preview, -p · boolean

Show a preview of the changes that would be made by the deploy command.

Usage:

Terminal

npx checkly deploy --preview
npx checkly deploy -p

Examples

Terminal

$ npx checkly deploy --preview

Parsing your project... ✅
Validating project resources... ✅
Bundling project resources... ✅

Create:
  UrlMonitor:: homepage-uptime
  MultiStepCheck: auth-api-flow

Delete:
  Check: legacy-api-check

Update and Unchanged:
  SmsAlertChannel: sms-channel-1

--preserve-resources · boolean

When a resource is removed from your code, checkly deploy deletes it from your account by default, which also permanently deletes its run history. Pass --preserve-resources to detach those resources instead: the project stops managing them, but the resources and their run history remain in your Checkly account as regular account-level resources. Detached resources can be re-attached later by adding them back to your code.

This mirrors checkly destroy --preserve-resources, but applies per-deploy to only the resources removed in that deploy rather than the whole project.

Usage:

Terminal

npx checkly deploy --preserve-resources

In the deploy output, detached resources are listed under a Detached (kept in account, now managed in the Checkly Webapp): section instead of Delete:.

--[no-]schedule-on-deploy · boolean · default: "true"

Prevent checks from running automatically when they are deployed.

Usage:

Terminal

npx checkly deploy --schedule-on-deploy
npx checkly deploy --no-schedule-on-deploy

Useful when you want to deploy changes but delay monitoring execution until later.

--[no-]verify-runtime-dependencies · boolean · default: "true"

Return an error if checks import dependencies that are not supported by the selected runtime.

Usage:

Terminal

npx checkly deploy --verify-runtime-dependencies
npx checkly deploy --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.

Deleting vs. detaching removed resources

When you remove a resource from your code and deploy, the CLI reconciles your account with your local configuration. By default, resources that no longer exist in code are deleted from your account, which also permanently deletes their run history.

Before performing any deletes, a non-forced checkly deploy first lists the resources that would be permanently deleted and asks you to confirm:

Terminal

$ npx checkly deploy

The following resources were removed from code and will be DELETED, losing their run history:
    Check: legacy-api-check

Pass --preserve-resources to detach and keep them (and their run history) instead.

This will:
  - Permanently delete 1 resource(s) removed from code, losing their run history
  - Delete Check: legacy-api-check

? Proceed? › (y/N)

This confirmation is skipped when you pass --force (for CI/CD), and it does not appear when you pass --preserve-resources. In agent or CI environments the CLI instead returns a confirmation_required JSON envelope and exits with code 2 rather than prompting.

To keep removed resources and their run history, deploy with --preserve-resources. Instead of deleting them, the CLI detaches them — they remain in your Checkly account as regular account-level resources, managed from the UI, and can be re-attached later by adding them back to your code:

Terminal

$ npx checkly deploy --preserve-resources --output

Detached (kept in account, now managed in the Checkly Webapp):
    Check: legacy-api-check

Successfully deployed project "Website Monitoring" to account "Monitoring as Code".

Detach-on-deploy requires a recent Checkly backend. Against older backends, --preserve-resources still keeps your resources, but they may be reported under Delete: rather than Detach: in the deploy output.

Git Integration

When you deploy a project, you can attach Git-specific information so changes to any resources are displayed in the Checkly web UI with the correct commit, branch, and author information.

The Checkly CLI evaluates Git information from your local or CI environment on a best effort basis. Override any automatically detected values by setting the corresponding environment variables.

Item	Auto	Variable	Description
Repository	false	repoUrl in checkly.config.ts or CHECKLY_REPO_URL	The URL of your repo on GitHub, GitLab etc.
Commit hash	true	CHECKLY_REPO_SHA	The SHA of the commit.
Branch	true	CHECKLY_REPO_BRANCH	The branch name.
Commit owner	true	CHECKLY_REPO_COMMIT_OWNER	The committer’s name or email.
Commit message	true	CHECKLY_REPO_COMMIT_MESSAGE	The commit message.
Environment	false	CHECKLY_TEST_ENVIRONMENT	The environment name, e.g. “staging”

Related Commands

• checkly login - Log in to your Checkly account
• checkly test - Test your setup before deployment