Authoring watches as files

Watches can be written as YAML files and imported. This is the right workflow if you want them reviewed, versioned, or created reproducibly.

Files are an import source, not the live truth

The running system reads watches from the database. Editing a file changes nothing until you import it. This is the single most common surprise for people who work this way.

Writing one

One watch per file, in watches/:

watches/framework-releases.yml

id: framework-releases
name: Framework stable releases
sources:
  - type: rss
    value: "https://example.com/blog/feed.xml"
    trust: official
  - type: search
    value: "framework 2.0 stable release"
    hints:
      recencyDays: 14
      topic: news
schedule: "0 */6 * * *"
condition: >
  Alert when a new stable version is released. Ignore release candidates,
  betas, and posts about future plans.
channels: [telegram]
threshold: 0.6
weakThreshold: 0.4
enabled: true

Every field is validated on import against the watch schema. An invalid file fails the import with the offending file named — nothing is partially applied.

Importing

pnpm watches:import

Imported 3 watch(es) from …/watches: 1 created, 2 updated.
  • framework-releases
  • product-restock
  • security-advisories

The import is an idempotent upsert keyed on id: running it repeatedly is safe, and it is the normal way to roll out an edit.

The workflow

1. Edit or add a file in watches/.
2. pnpm watches:import.
3. pnpm run-due:force to test it immediately.
4. pnpm watches history <id> to read the outcome.

What import does not do

• It does not delete. Removing a file leaves the watch in the database. Delete it explicitly with pnpm watches delete <id>.
• It does not merge. An imported watch replaces the stored definition, so a field you removed from the file is removed from the watch.
• It does not preserve panel edits. If someone edits a watch in the panel and you then import an older file, the file wins. Pick one source of authority per watch.

Ownership

Imported watches take the ownerId in the file, defaulting to local. If you bootstrapped your admin account with --id local, imported watches are yours and appear in the panel. If not, they belong to a different owner and will not show up — set ownerId explicitly in the file to fix that.

Keeping files private

Caution

A watch definition contains your condition — which often reveals what you are watching and why. If you commit watches/*.yml to a repository, treat it as you would any other personal file: keep the repository private, or write conditions that do not disclose more than you intend.

Managing without files

Everything here is also available through the API and the panel — files are one option, not a requirement. See Watches API.