﻿Any string value in `runwisp.toml` can take its value from the daemon's
environment or from a file:

```toml title="runwisp.toml"
[tasks.backup]
cron        = "${BACKUP_CRON}"          # from the daemon's environment
description = "backs up ${REGION}"      # works inside a longer string
run         = "/usr/local/bin/backup.sh"

[notifiers.slack-ops]
type        = "slack"
webhook_url = "${file:secrets/slack.url}"   # from a file
```

It works on every string value (cron, paths, env values, notifier credentials,
compose blocks) except [`run`](#the-exception-run). Use it to keep credentials
out of the TOML file.

## `${VAR}`: environment variables

`${VAR}` is replaced with `VAR` from the **daemon's** environment (the shell,
systemd unit, or container that started `runwisp daemon`).

- An unset variable is a config-load error that names the variable and the key:

    ```text
    tasks.backup.cron: environment variable BACKUP_CRON is not set
    ```

- A variable that is set but empty gives an empty string.
- A daemon installed as a service doesn't see your shell. See
  [Other variables](/operations/autostart/#other-variables) for how to give it
  one.
- Since 1.6, `${HOSTNAME}` falls back to the machine's hostname when the
  variable isn't set. Shells often don't export it, and systemd and launchd
  never set it.

## `${file:path}`: file contents

`${file:path}` is replaced with the file's contents, with leading and trailing
whitespace removed (so a trailing newline doesn't break a token).

- A missing or unreadable file is a config-load error.
- Paths can be absolute, `~/...` (your home directory), or relative to the
  directory of `runwisp.toml`.
- Works well with files written by a secrets tool (Vault agent, sops, Docker
  secrets in `/run/secrets/...`). Set the file to `chmod 600`.

## When it runs

Substitution runs once, when the config is loaded: at startup and on
[`runwisp reload`](/operations/reload/). The daemon doesn't watch the
environment or the files. After a change, reload or restart.

## The exception: `run`

[`run`](/configuration/tasks/#run) (on tasks and services) is **never**
substituted. The shell expands `${VAR}` in it at run time, using the full process
environment, including [`env`](/configuration/tasks/#env),
[`env_file`](/configuration/tasks/#env_file),
[`secrets`](/configuration/tasks/#secrets), and
[`secrets_file`](/configuration/tasks/#secrets_file):

```toml title="runwisp.toml"
[tasks.backup]
run = "backup.sh --bucket ${BACKUP_BUCKET}"   # the shell expands this

[tasks.backup.env]
BACKUP_BUCKET = "s3://prod-backups"
```

## What else is not substituted

- **Keys.** Env var names, task names, and compose service names stay as
  written. Only values are substituted.
- **Referenced files.** Dotenv files ([`env_file`](/configuration/tasks/#env_file),
  [`secrets_file`](/configuration/tasks/#secrets_file)) and compose files
  ([`compose_file`](/configuration/tasks/#compose_file)) are read as they are.
- **Crontabs** read through [`include_cron`](/configuration/daemon/#include_cron).

## Escaping

Write `$${` for a literal `${`:

```toml title="runwisp.toml"
[tasks.report]
# ...
description = "template is $${VAR}"   # → template is ${VAR}
```

- A single `$` (like `cost: $5`) needs no escaping.
- An unclosed `${` (no `}`) is a config-load error.
- `runwisp import` escapes `${` for you, because cron and supervisord don't
  substitute. Imported text keeps its meaning. To make an imported value
  substitute, remove the extra `$`.

## Worked example

```toml title="runwisp.toml"
[tasks.export]
cron = "${EXPORT_CRON}"
run  = "/usr/local/bin/export"

[tasks.export.secrets]
API_TOKEN = "${file:secrets/export.token}"

[notifiers.slack-ops]
type        = "slack"
webhook_url = "${SLACK_OPS_WEBHOOK}"

[notifiers.tg-oncall]
type      = "telegram"
bot_token = "${file:~/.config/runwisp/tg.token}"
chat_id   = "-1001234567890"
```

Start the daemon with `EXPORT_CRON` and `SLACK_OPS_WEBHOOK` set and the token
files at `0600`. The TOML file then contains no secrets.
