> ## Documentation Index > Fetch the complete documentation index at: https://checkly-422f444a-simo-red-943-deploy-diff.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # checkly deploy > Deploy checks and resources to your Checkly account. export const command_0 = "checkly deploy" 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 {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 deploys all resources to your Checkly account, synchronizing your local monitoring-as-code configuration with the Checkly monitoring infrastructure. ```bash Terminal theme={null} 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. | | `--cancel-in-progress-deployment` | - | If a deployment for this project is already in progress, cancel it instead of waiting for it to finish. | | `--debug-bundle` | - | Write the data a deploy would send to `./debug-bundle.json` and exit without deploying anything. **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. | | `--dry-run` | - | Print the plan as JSON and exit without deploying. | | `--output, -o` | - | Show the changes made after the deploy command, with a diff of every updated resource. | | `--plan-token` | - | Deploy only if the plan still matches this token from an earlier run. Aborts if anything changed in your Checkly account since then. | | `--preview, -p` | - | Show a preview of the changes made by the deploy command, with a diff of every updated resource. | | `--preserve-resources` | - | Detach resources removed from code (keeping them and their run history) instead of deleting them. | | `--prune-relations` | - | Delete the alert channel subscriptions and private location assignments on this project's checks and groups that the project does not manage. | | `--[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. | | `--verbose, -v` | - | Show resource names and IDs in the deploy output. Implies `--output`. | ## 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: ` 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`](#command-options). 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 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:** ```bash Terminal theme={null} npx checkly deploy --cancel-in-progress-deployment ``` 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 deploy --config="./checkly.staging.config.ts" npx checkly deploy -c="./checkly.staging.config.ts" ``` 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:** ```bash Terminal theme={null} npx checkly deploy --dry-run ``` 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:** ```bash Terminal theme={null} npx checkly deploy --force npx checkly deploy -f ``` **Examples** ```bash Terminal theme={null} $ npx checkly deploy --force Parsing your project... ✅ Validating project resources... ✅ Bundling project resources... ✅ Checking what would change... ✅ Deploying project... ✅ Successfully deployed project "Website Monitoring" to account "Monitoring as Code". ``` Show the changes after deploying, in the same layout as [`--preview`](#command-options), including the diff of every updated resource. **Usage:** ```bash Terminal theme={null} npx checkly deploy --output npx checkly deploy -o ``` **Examples:** ```bash Terminal theme={null} $ npx checkly deploy --output --force Parsing your project... ✅ Validating project resources... ✅ Bundling project resources... ✅ Checking what would change... ✅ Deploying project... ✅ Update: ApiCheck: homepage-api file: __checks__/homepage.check.ts --- deployed +++ local @@ -1,7 +1,7 @@ new ApiCheck('homepage-api', { name: 'Homepage API', request: { - url: 'https://example.com/health', + url: 'https://example.com/v2/health', method: 'GET', }, }) Unchanged: 12 Successfully deployed project "Website Monitoring" to account "Monitoring as Code". ``` 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:** ```bash Terminal theme={null} npx checkly deploy --plan-token v1.Yq2PnD7Kzx0m8sVxLh4cQw ``` 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:** ```bash Terminal theme={null} npx checkly deploy --preview npx checkly deploy -p ``` **Examples** ```bash Terminal theme={null} $ npx checkly deploy --preview Parsing your project... ✅ Validating project resources... ✅ Bundling project resources... ✅ Checking what would change... ✅ Create: UrlMonitor: homepage-uptime MultiStepCheck: auth-api-flow Delete: Check: legacy-api-check Update: SmsAlertChannel: sms-channel-1 file: __checks__/alert-channels.ts --- deployed +++ local @@ -1,4 +1,4 @@ export const smsChannel1Alert = new SmsAlertChannel('sms-channel-1', { name: 'On-call phone', - phoneNumber: '+31612345678', + phoneNumber: '+31687654321', }) Unchanged: 12 Plan token: v1.Yq2PnD7Kzx0m8sVxLh4cQw Deploy this exact plan with `checkly deploy --plan-token v1.Yq2PnD7Kzx0m8sVxLh4cQw`. ``` The lines printed under an updated resource are described in [How a deploy previews its changes](#how-a-deploy-previews-its-changes). 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`](/cli/checkly-destroy), but applies per-deploy to only the resources removed in that deploy rather than the whole project. **Usage:** ```bash Terminal theme={null} npx checkly deploy --preserve-resources ``` In the deploy output, detached resources are listed in their own section instead of under `Delete:`; see [Deleting vs. detaching removed resources](#deleting-vs-detaching-removed-resources). 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:** ```bash Terminal theme={null} npx checkly deploy --prune-relations ``` 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:** ```bash Terminal theme={null} npx checkly deploy --no-schedule-on-deploy ``` Return an error if checks import dependencies that are not supported by the selected runtime. **Usage:** ```bash Terminal theme={null} 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](/detect/synthetic-monitoring/playwright-checks/overview) because they don't rely on a specific runtime. 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:** ```bash Terminal theme={null} npx checkly deploy --verbose npx checkly deploy -v ``` ## 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: ```bash Terminal theme={null} $ npx checkly deploy Parsing your project... ✅ Validating project resources... ✅ Bundling project resources... ✅ Checking what would change... ✅ This will: - Deploy project "Website Monitoring" to account "Monitoring as Code" - Schedule checks after deploy - Delete any resources removed from code, losing their run history. Pass --preserve-resources to keep them in your Checkly account instead - Permanently delete Check: legacy-api-check, losing its run history - Update Check: homepage-api ? Proceed? › (y/N) ``` 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`](#command-options). 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: ```bash Terminal theme={null} $ npx checkly deploy --preserve-resources --output Kept in your Checkly account (removed from code, now managed from the Checkly web app): 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 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. | 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`](/cli/checkly-login) - Log in to your Checkly account * [`checkly test`](/cli/checkly-test) - Test your setup before deployment