🤖 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:

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 on pushes to the release-cli branch.

Commit format

Use Conventional Commits 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 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