# 🤖 Appwarden

> CLI to manage Appwarden monitors and deployments. Learn more at https://appwarden.io/docs/getting-started

## Features

- **HTTP/2 Support**: Automatically uses HTTP/2 when probing domains (with automatic fallback to HTTP/1.1)
- **DNS Monitoring**: Track DNS records for your domains
- **Website Monitoring**: Monitor HTTP status codes and response headers
- **Vercel Auto-Detection**: Automatically detects and configures CIDR block validation for Vercel-hosted domains

## Usage

Run the CLI with the following command:

```
> npx appwarden [command] [options]
```

To see the commands and parameters of the application, you can use the -h or --help parameter:

```
> npx appwarden --help
```

## Commands

### 🚀 init

Set up Appwarden directory and scaffold your domain configuration files

> A domain configuration file in Appwarden is a YAML file that defines monitoring settings for a specific domain. It includes sections for DNS and website monitors, specifying the hostname, DNS records, and website URLs to be monitored, along with their expected statuses and headers. This file helps Appwarden track and alert on unexpected changes to the domain's web infrastructure and response headers.

#### Options

| Option                    | Description                                                            |
| ------------------------- | ---------------------------------------------------------------------- |
| `-d, --domain [hostname]` | Create a domain configuration file for this domain (e.g. appwarden.io) |
| `--vercel`                | Add Vercel-specific DNS monitoring with CIDR block validation          |

#### Description

Domain configuration files are stored in a GitHub repository that you own, ensuring everything is in one place, making it easier to manage, track changes, and collaborate alongside your other source-controlled code.

You can manage your configuration files by using either a new or an existing repository. If you are monitoring multiple projects with Appwarden, it's best to initialize it in a new repository. For single projects, we recommend setting it up within your existing project repository.

After initialization, simply open a pull request to your main branch to complete the Appwarden setup.

#### Behavior

When running `init` on a domain configuration file that already exists:

- **Preserves existing configuration**: Middleware settings, DNS options, and website options are kept intact
- **Selective updates**: Only DNS and website monitors for domains specified with `-d` are updated
- **Non-destructive merging**: Monitors for domains not specified in the command remain unchanged

For example, if you have a configuration file with `example.com`, `api.example.com`, and `cdn.example.com` monitors, running:

```bash
npx appwarden sync -d example.com
```

Will update only the DNS and website monitors for `example.com`, while preserving all monitors for `api.example.com` and `cdn.example.com`, as well as any middleware configuration.

#### Examples

```
# Set up Appwarden for our project's domains
> npx appwarden sync -d appwarden.io -d appwarden.online

# Vercel domains are auto-detected - CIDR validation is applied automatically
> npx appwarden sync -d myapp.vercel.app

# Manual Vercel flag (optional override)
> npx appwarden sync -d myapp.vercel.app --vercel

# Update only specific subdomains while preserving other configuration
> npx appwarden sync -d app.example.com -d dashboard.example.com
```

### Vercel Auto-Detection

Appwarden automatically detects when a domain is hosted on Vercel by checking if the resolved A record IPs fall within Vercel's known CIDR blocks. When detected:

- ✅ Automatically enables CIDR block validation for A records
- ✅ Handles Vercel's rotating IP addresses seamlessly
- ✅ No manual `--vercel` flag required

The `--vercel` flag can still be used as a manual override in edge cases where auto-detection may not work.

## Releasing

Releases are automated via [semantic-release](https://semantic-release.gitbook.io/) on pushes to the `release-cli` branch.

### Commit format

Use [Conventional Commits](https://www.conventionalcommits.org/) with these custom types to trigger version bumps:

| Commit type | Version bump | Example commit message                    |
| ----------- | ------------ | ----------------------------------------- |
| `patch`     | Patch        | `patch: fix DNS record comparison logic`  |
| `minor`     | Minor        | `minor: add support for wildcard domains` |
| `major`     | Major        | `major: drop support for Node 18`         |

### Release workflow

1. Open a PR with your changes using the commit format above
2. Merge the PR into the `release-cli` branch
3. The [`release-cli.yml`](../../.github/workflows/release-cli.yml) GitHub Action runs:
   - Builds the CLI and runs tests
   - Runs `semantic-release` to determine the next version
   - Publishes to npm as `appwarden@<version>`
   - Tags the release as `appwarden@<version>`
   - Auto-merges `release-cli` back into `main`