> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# deploy

> DevHelm CLI deploy commands — validate, plan, deploy, and force-unlock config-as-code workflows

Deploy your monitoring configuration from YAML files. Validate syntax, preview changes, apply updates, and manage deploy locks.

## Commands

| Command                       | Description                           |
| ----------------------------- | ------------------------------------- |
| `devhelm validate <file>`     | Validate config file syntax (offline) |
| `devhelm plan -f <file>`      | Preview changes without applying      |
| `devhelm deploy -f <file>`    | Apply config changes                  |
| `devhelm deploy force-unlock` | Release a stuck deploy lock           |

## devhelm validate

Validate a configuration file offline. No API calls are made — this checks YAML syntax and schema validity. The file argument is optional and defaults to `devhelm.yml`.

```bash theme={null}
devhelm validate devhelm.yml
```

| Flag             | Type    | Default | Description                                                                                   |
| ---------------- | ------- | ------- | --------------------------------------------------------------------------------------------- |
| `--strict`       | boolean | `false` | Fail on schema warnings (unused secrets, unknown fields, etc.) — not just hard errors         |
| `--skip-env`     | boolean | `false` | Skip `${VAR}` substitution checks — useful when validating templates without the env vars set |
| `-o`, `--output` | enum    | `text`  | `text` or `json` — note this differs from list commands which support `table\|json\|yaml`     |

Use this in CI as an early check before running `plan` or `deploy`. Pair with `--strict` in pre-merge checks to surface drift you'd otherwise only catch at deploy time.

## devhelm plan

Preview what would change without applying anything. Equivalent to `deploy --dry-run`.

```bash theme={null}
devhelm plan -f devhelm.yml
```

The output shows resources to create, update, and delete.

| Flag                  | Short | Type    | Default       | Description                                 |
| --------------------- | ----- | ------- | ------------- | ------------------------------------------- |
| `--file`              | `-f`  | string  | `devhelm.yml` | Config file or directory (repeatable)       |
| `--prune`             | —     | boolean | `false`       | Include state-tracked deletions in the plan |
| `--prune-all`         | —     | boolean | `false`       | Include all unmanaged deletions in the plan |
| `--detailed-exitcode` | —     | boolean | `false`       | Exit `10` when the plan has pending changes |
| `--output`            | `-o`  | string  | `text`        | Output format: `text` or `json`             |

## devhelm deploy

Apply configuration changes.

```bash theme={null}
devhelm deploy -f devhelm.yml --yes
```

### Flags

| Flag                  | Short | Type    | Default       | Description                                                                        |
| --------------------- | ----- | ------- | ------------- | ---------------------------------------------------------------------------------- |
| `--file`              | `-f`  | string  | `devhelm.yml` | Config file or directory (repeatable)                                              |
| `--yes`               | `-y`  | boolean | `false`       | Skip confirmation prompt (required in CI)                                          |
| `--prune`             | —     | boolean | `false`       | Delete resources tracked in this config's state file that are absent from the YAML |
| `--prune-org-cli`     | —     | boolean | `false`       | Also delete CLI-managed resources from other configs in the org                    |
| `--prune-all`         | —     | boolean | `false`       | Delete all resources absent from config, regardless of how they were created       |
| `--dry-run`           | —     | boolean | `false`       | Preview changes without applying                                                   |
| `--detailed-exitcode` | —     | boolean | `false`       | Exit `10` if dry-run has pending changes                                           |
| `--force-unlock`      | —     | boolean | `false`       | Break existing lock before acquiring                                               |
| `--no-lock`           | —     | boolean | `false`       | Skip deploy locking                                                                |
| `--lock-timeout`      | —     | integer | `0`           | Seconds to wait for lock (`0` = fail immediately)                                  |
| `--output`            | `-o`  | string  | `text`        | Output format: `text` or `json`                                                    |
| `--api-token`         | —     | string  | —             | Override API token                                                                 |
| `--api-url`           | —     | string  | —             | Override API base URL                                                              |
| `--verbose`           | `-v`  | boolean | `false`       | Enable debug logging                                                               |

### Multiple config files

Pass `-f` multiple times to deploy from multiple files:

```bash theme={null}
devhelm deploy -f monitors.yml -f alert-channels.yml --yes
```

### Pruning

By default, `deploy` only creates and updates resources defined in your config. Resources not in the file are left untouched. Three pruning scopes, from safest to most destructive:

* **`--prune`** deletes resources tracked in **this config's** `.devhelm/state.json` that are no longer in the YAML. Safe in multi-config orgs — it never touches CLI-managed resources owned by other configs.
* **`--prune-org-cli`** widens `--prune` to **all CLI-managed resources in the org**, even those created from other config files. Use with caution in shared workspaces.
* **`--prune-all`** deletes **all** resources not in the config, including those created via the dashboard, Terraform, or the API.

```bash theme={null}
devhelm deploy -f devhelm.yml --prune --yes
```

<Warning>
  `--prune-org-cli` and `--prune-all` delete resources created outside this config file. Use with caution.
</Warning>

### Dry-run with exit codes

Combine `--dry-run` and `--detailed-exitcode` for CI gating:

```bash theme={null}
devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
```

| Exit code         | Meaning                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| `0`               | No changes needed                                                      |
| `10`              | Changes pending                                                        |
| `4` / `11` / `12` | Validation / API / transport error (see [Exit codes](/cli/exit-codes)) |

### Deploy locking

Only one deploy can run at a time per organization. If a lock is held by another process, the CLI fails immediately by default.

Use `--lock-timeout` to wait:

```bash theme={null}
devhelm deploy -f devhelm.yml --yes --lock-timeout 60
```

Use `--no-lock` to skip locking entirely (not recommended for shared environments):

```bash theme={null}
devhelm deploy -f devhelm.yml --yes --no-lock
```

## devhelm deploy force-unlock

Release a stuck deploy lock manually.

```bash theme={null}
devhelm deploy force-unlock --yes
```

| Flag    | Short | Type    | Description              |
| ------- | ----- | ------- | ------------------------ |
| `--yes` | `-y`  | boolean | Skip confirmation prompt |

<Warning>
  Only force-unlock if you're certain no other deploy is running. Unlocking during an active deploy can cause inconsistent state.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Monitoring as Code" icon="file-code" href="/guides/monitoring-as-code">
    Full YAML format and workflow guide.
  </Card>

  <Card title="GitHub Actions" icon="github" href="/integrations/github-actions">
    Automate deploys from CI.
  </Card>

  <Card title="CI/CD pipeline guide" icon="wrench" href="/guides/ci-cd-pipeline">
    End-to-end CI/CD setup.
  </Card>
</CardGroup>