Environment variables

Environment variables

Every CronWatch library reads a handful of environment variables, so the dashboard’s token and the cron secret can stay out of your code. Their names are part of the 1.x promise. An option passed in code always wins over the variable, and a variable set to an empty string, or only spaces, counts as not set.

The ones every library reads

@cronwatch/mcp reads two: CRONWATCH_URL, where the dashboard is mounted (the --url flag wins; with neither it exits), and CRONWATCH_TOKEN, the bearer it sends (the --token flag wins; without one it works only against an open dashboard, and says so). See MCP server.

Development and production

Development decides two things: a dashboard with no token makes one of its own and prints it, and a handler with no secret runs. Production decides one: the default in-memory store warns that it forgets on restart. Every library names the environment the same way:

1. Take the first variable in the language’s order (below) whose value, trimmed, is not empty, and lowercase it.
2. prod means production. dev, local, test and testing mean development, as development does.
3. With nothing set, the environment is neither, so there is no development token and no unguarded handler.

By language

Besides the ones above, each library reads these.

TypeScript

Ruby

The Rails install generator writes an initializer that reads SLACK_WEBHOOK_URL, with DISCORD_WEBHOOK_URL, CRONWATCH_WEBHOOK_URL and CRONWATCH_WEBHOOK_SECRET in comments. That code is yours to change; the gem itself does not read them.

Python

Django reads no variable of its own: its settings go in the CRONWATCH dict in settings.py (TOKEN first, then CRONWATCH_TOKEN). See Django.

PHP

Variables are read from getenv(), then $_ENV, then $_SERVER.

cronSecret, the dashboard’s token and a handler’s secret read CRON_SECRET and CRONWATCH_TOKEN when left out (or given Cronwatch\FromEnv::Read); null turns them off. The integrations:

• Laravel reads its settings from config/cronwatch.php, whose values come from the variables in the table below.
• Symfony has no variables of its own: write %env(...)% in config/packages/cronwatch.yaml. Left unset, cron_secret reads CRON_SECRET, dashboard.token reads CRONWATCH_TOKEN, and store uses DATABASE_URL, else var/cronwatch.db.
• WordPress reads only WP_ENVIRONMENT_TYPE; its token and channels are the plugin’s settings, and it has no cron secret.
• Drupal uses the cronwatch_token setting, else CRONWATCH_TOKEN, and reads CRON_SECRET.
• Craft CMS uses the apiToken setting, else CRONWATCH_TOKEN, and reads CRON_SECRET; any setting written as $NAME is read from that variable, as Craft does.

Laravel’s variables, each filling one key of config/cronwatch.php:

See Laravel for what each key does.

Go

sqlstore reads no DATABASE_URL: open the *sql.DB yourself.

Rust

cronwatch-sqlx reads no variable: pass it your pool.

Elixir

CRON_SECRET and CRONWATCH_TOKEN are read on each request, so a release picks up a changed value without a restart. token: {:system, "NAME"} and a handler’s secret: {:system, "NAME"} read a variable of your choosing first. cron_secret: false turns the secret off.

Java

A schedule with no zone is read in the JVM’s default zone, which follows TZ and -Duser.timezone. The Spring Boot starter’s settings are the cronwatch.* and cronwatch.web.* properties, which Spring Boot also reads from variables by its relaxed binding: CRONWATCH_WEB_TOKEN sets cronwatch.web.token. Left unset, cronwatch.cron-secret reads CRON_SECRET and cronwatch.web.token reads CRONWATCH_TOKEN. See Java schedulers.

.NET

Cronwatch.Hosting reads the Cronwatch configuration section (Retention, Token, CheckEvery, Environment), which the default host also fills from variables such as Cronwatch__Token. A schedule with no zone is read in TimeZoneInfo.Local, which follows TZ on Linux and macOS. See .NET.