Skip to main content
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.
Before using checkly deploy, 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

​
How a deploy previews its changes

Before it writes anything, checkly deploy asks Checkly what the deploy would change and shows you the plan. A plain checkly deploy lists the resources it would create, update or delete and asks you to confirm: deletions are always listed in full, created and updated resources up to 20, with the rest counted and --preview suggested for the full list. While the plan is being checked nothing is uploaded, so cancelling at the prompt leaves your account untouched. The plan compares your code against what the project last deployed, so it can also tell you when a resource was edited in the Checkly web app or through the API since then. Such an edit is overwritten by the deploy, because your code is the source of truth for the resources it declares; the property listing and the --dry-run envelope mark it as changed in Checkly, while the construct diff simply shows your account’s current value on the deployed side. Under an updated resource, --preview and --output print a diff of the construct as it is in your account against the construct in your code. You may also see:
  • A diff of two texts rather than of the construct, for a change that lives outside it: a browser or multi-step check’s script, an API check’s setup or teardown script.
  • A property Checkly stores encrypted, such as a locked environment variable, is shown inline with its value masked as '********'. The side that changed reads '******** (changed)', or '******** (changed in Checkly)' on the deployed side. When the change cannot be shown inline, for example a secret that was renamed, the line secret changed: <property> names the property holding it instead.
  • changed: code bundle or changed: dependency cache, or one line naming both, for a resource whose only change is what it bundles.
  • payload format changed (CLI upgrade) when the only differences come from a newer CLI describing the same construct differently, such as a private location list or retry strategy being sent in a new form. The deploy rewrites the stored form and nothing about the resource changes.
  • A plain list of the changed properties when the CLI cannot render the resource as a construct.
Checks marked testOnly: true are not deployed and are listed under Skip (testOnly):. Every plan comes with a plan token that pins the account state it was computed against, so a deploy cannot silently apply to an account that changed in the meantime. See --plan-token. Resources that did not change are not written at all. Deploying the same code twice reports every resource as unchanged the second time.
When the plan cannot be computed, the CLI warns Could not check what this deploy would change and falls back to listing the resources a deploy would touch, without property-level detail and with the code bundle uploaded before the confirmation; --plan-token and --prune-relations are unavailable on that path.

​
Command Options

​
boolean
A deploy waits for a deployment of the same project that is still in progress. When that wait runs out, the CLI reports A deployment for this project is still in progress. Pass this flag to cancel the running deployment and deploy now instead of waiting.Usage:
Terminal
​
string
Specify a configuration file to use instead of the checkly.config.ts or checkly.config.js in the current directory.Usage:
Terminal
​
boolean
Print the plan as a JSON envelope and exit without deploying. The envelope carries every resource the deploy would touch and, for each updated one, the changed properties with their values before and after, together with the plan token. A value longer than 256 characters (a script, a request body) is replaced by an $omitted marker carrying its length. A sensitive value is a { "$masked": "same" | "changed" } marker, changed on the element whose secret moved. A change is flagged secret: true when a secret moved or when a sensitive list element has no counterpart on the other side (added, removed or renamed), in which case no marker reads changed and the list itself shows the difference. The deployed state itself is not included. Useful for scripts and agents that want to inspect a deploy before running it with --plan-token.Usage:
Terminal
​
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. A forced deploy still computes the plan; if the account changes while the code bundle is uploading, it plans again and deploys the current plan rather than failing the pipeline. A run pinned with --plan-token is refused instead, even with --force.Usage:
Terminal
Examples
Terminal
​
boolean
Show the changes after deploying, in the same layout as --preview, including the diff of every updated resource.Usage:
Terminal
Examples:
Terminal
​
string
Deploy exactly the plan an earlier checkly deploy --preview or --dry-run showed. The token is a fingerprint of your account’s state at that time; if anything changed since, the deploy refuses and nothing is deployed, instead of overwriting an edit nobody reviewed. Run checkly deploy --preview again to see the current plan and get a fresh token.Usage:
Terminal
​
boolean
Show a preview of the changes that would be made by the deploy command, without deploying. Every updated resource is printed with a diff of its construct as it is in your account against as it is in your code, and the plan token is printed at the end.Usage:
Terminal
Examples
Terminal
The lines printed under an updated resource are described in How a deploy previews its changes.
​
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
In the deploy output, detached resources are listed in their own section instead of under Delete:; see Deleting vs. detaching removed resources.
​
boolean
Alert channel subscriptions and private location assignments can be added to a check or group from the Checkly web app, outside your code. A deploy leaves those alone and reports them as relations the project does not manage. Pass --prune-relations to delete them, so the check or group ends up with exactly the alert channels and private locations your code declares.Without the flag, a check or group whose only reported change is such a relation is listed under Has alert channels or private locations this project does not manage (pass --prune-relations to delete them):. With it, the relations to be deleted are listed under Prune (relations not managed by this project): and named in the confirmation, so you can see what goes before it does.Usage:
Terminal
​
boolean
default:"true"
Checks are scheduled to run as soon as they are deployed. Pass --no-schedule-on-deploy to deploy them without scheduling, which is useful when you want to deploy changes but delay monitoring execution until later.Usage:
Terminal
​
boolean
default:"true"
Return an error if checks import dependencies that are not supported by the selected runtime.Usage:
Terminal
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.
​
boolean
Show the name and the ID of every created and updated resource in the deploy output. Implies --output, so the changes are printed after the deploy, with their diffs.Usage:
Terminal

​
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. A non-forced checkly deploy shows you the plan and asks you to confirm it:
Terminal
This confirmation is skipped when you pass --force (for CI/CD). In agent or CI environments the CLI instead returns a confirmation_required JSON envelope carrying the plan and its token, and exits with code 2 rather than prompting; the envelope names the command that deploys that exact plan. 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
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 under the kept-in-account section 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.