recur

module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 12, 2026 License: MPL-2.0

README

Recur

CI Lint

Recur is a cross-platform configuration-driven automation toolset consisting of a daemon and CLI supported by a flexible plugin system. It is written in Go and runs locally on the system.

Simply define what events to wait for — file changes, cron schedules, webhooks, MQTT messages, calendar events, USB devices, or Docker containers — and how to respond.

Install

Pre-built binaries for Linux (amd64, arm64, armv7, i386) and macOS (amd64, arm64) are available on the Releases page. Each release ships a sha256 checksum file and a Sigstore cosign signature — see VERIFYING.md for the verify commands.

Using Go 1.25+:

go install github.com/directedbits/recur/src/app/recur@latest   # CLI
go install github.com/directedbits/recur/src/app/recurd@latest  # Daemon

Building from source:

git clone https://github.com/directedbits/recur.git
cd recur
task build    # outputs bin/recur and bin/recurd

Quick Start

# Start the daemon
recur start

# Create a config file with stubbed values for a FileCreated trigger and shell execution action
recur add MyProject FileCreated --actions=shell --stub --edit

# Check status
recur status

The add command writes the recurfile and auto-registers it with the daemon. Use recur register to register an existing recurfile manually.

Example Configuration

Build:
  on:
    - type: cron
      options:
        expression: "0 2 * * *"
  do:
    - shell: "make build"

Deploy:
  on:
    - type: WebhookReceived
      options:
        port: "9090"
        path: "/deploy"
        secret: "my-secret"
  do:
    - shell: "deploy.sh"

See the recurfile format documentation for the full syntax including template variables, aliases, group options, and scopes.

Plugins

Plugin Triggers Actions Description
fileevents FileCreated, FileModified, FileDeleted, FileMoved, FileAttributeChanged — File system event monitoring
timer cron, interval — Cron schedule and interval triggers
webhook WebhookReceived — HTTP/HTTPS webhook receiver with HMAC verification
mqtt MessageReceived publish MQTT subscribe and publish
calendar EventUpcoming, EventStarted, EventEnded — iCal/ICS calendar polling
devicemonitor DeviceConnected, DeviceDisconnected — USB/device hotplug (Linux + Windows)
docker ContainerStarted, ContainerStopped, HealthChanged ContainerStart, ContainerStop, ContainerRestart Docker container lifecycle

How It Works

  1. The daemon (recurd) runs in the background, managing the plugin lifecycle and trigger/action registry
  2. Config files declare what triggers to listen for and what actions to take
  3. Plugins are standalone binaries that implement triggers and actions via an exec-based contract (stdin JSON for config, gRPC callback for events)
  4. The CLI (recur) communicates with the daemon via a Unix socket, with graceful fallback to file reads when the daemon isn't running

State is persisted to ~/.config/recur/state/state.json so triggers and their error counts survive restarts.

Documentation

Contributing

See CONTRIBUTING.md for development setup, coding standards, and how to submit changes.

Security

See SECURITY.md for the security policy and how to report vulnerabilities.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

License

This project is licensed under the Mozilla Public License 2.0.

Directories

Path Synopsis
pkg
config module
src
app/recur command
app/recur/cli
Package cli provides the CLI command definitions and Cobra setup.
 Package cli provides the CLI command definitions and Cobra setup.
app/recur/text
Package text holds generic string-matching utilities used by the CLI for "did you mean…?" suggestions.
 Package text holds generic string-matching utilities used by the CLI for "did you mean…?" suggestions.
app/recurd command
app/recurd/daemon
Package daemon provides the daemon orchestration layer — startup, shutdown, and coordination of triggers, actions, and plugins.
 Package daemon provides the daemon orchestration layer — startup, shutdown, and coordination of triggers, actions, and plugins.
app/recurd/triggerengine
Package trigger provides the generic trigger engine that manages drivers and dispatches trigger events to action execution.
 Package trigger provides the generic trigger engine that manages drivers and dispatches trigger events to action execution.
domain/action
Package action defines the action aggregate — units of work executed when a trigger fires.
 Package action defines the action aggregate — units of work executed when a trigger fires.
domain/config
Package config defines the daemon configuration shape and pointer helpers.
 Package config defines the daemon configuration shape and pointer helpers.
domain/group
Package group defines the group aggregate — a named collection of triggers and actions within a recurfile.
 Package group defines the group aggregate — a named collection of triggers and actions within a recurfile.
domain/plugin
Package plugin defines the plugin aggregate — loadable extensions that provide triggers and actions.
 Package plugin defines the plugin aggregate — loadable extensions that provide triggers and actions.
domain/recurfile
Package recurfile builder.go encodes the rules for turning a resolved RawFile into the data fields of trigger/action/group/recurfile entities.
 Package recurfile builder.go encodes the rules for turning a resolved RawFile into the data fields of trigger/action/group/recurfile entities.
domain/secret
Package secret defines the recurfile secret shape and resolver abstraction.
 Package secret defines the recurfile secret shape and resolver abstraction.
domain/trigger
Package trigger defines the trigger aggregate — the core unit of event detection.
 Package trigger defines the trigger aggregate — the core unit of event detection.
infra/fs/atomicfile
Package atomicfile provides crash-safe file writes using timestamped temp files.
 Package atomicfile provides crash-safe file writes using timestamped temp files.
infra/fs/plugin
Package plugin handles plugin discovery and lifecycle management.
 Package plugin handles plugin discovery and lifecycle management.
infra/grpc/client
infra/grpc/recur/v1
infra/grpc/server
Package servergrpc implements the daemon-side gRPC: server lifecycle, listener transport, and proto<->domain conversion for inbound requests.
 Package servergrpc implements the daemon-side gRPC: server lifecycle, listener transport, and proto<->domain conversion for inbound requests.
infra/jsonfile/state
Package state handles reading and writing daemon state to ~/.config/recur/state/state.json.
 Package state handles reading and writing daemon state to ~/.config/recur/state/state.json.
infra/os/defaults
Package defaultsos exposes platform-specific defaults used to construct the daemon's Config.
 Package defaultsos exposes platform-specific defaults used to construct the daemon's Config.
infra/os/process
Package process handles daemon process management — PID files, subprocess spawning, signal handling.
 Package process handles daemon process management — PID files, subprocess spawning, signal handling.
infra/secret/composite
Package secretcomposite dispatches a SecretDef to one of the per-source resolvers (env, file, keyring) based on SecretDef.Source.
 Package secretcomposite dispatches a SecretDef to one of the per-source resolvers (env, file, keyring) based on SecretDef.Source.
infra/secret/env
Package secretenv resolves SecretDefs whose source is "env" by reading environment variables.
 Package secretenv resolves SecretDefs whose source is "env" by reading environment variables.
infra/secret/file
Package secretfile resolves SecretDefs whose source is "file" by reading the file at def.Ref.
 Package secretfile resolves SecretDefs whose source is "file" by reading the file at def.Ref.
infra/secret/keyring
Package secretkeyring resolves SecretDefs whose source is "keyring" by reading from the OS keyring.
 Package secretkeyring resolves SecretDefs whose source is "keyring" by reading from the OS keyring.
infra/subprocess/executor
Package executor handles subprocess execution for plugin actions.
 Package executor handles subprocess execution for plugin actions.
infra/terminal/display
Package display formats domain values and gRPC errors for terminal output.
 Package display formats domain values and gRPC errors for terminal output.
infra/yaml/config
Package config handles loading and persisting daemon configuration from ~/.config/recur/config.yaml.
 Package config handles loading and persisting daemon configuration from ~/.config/recur/config.yaml.
infra/yaml/manifest
Package manifest handles loading and validating plugin manifest files (manifest.yaml).
 Package manifest handles loading and validating plugin manifest files (manifest.yaml).
infra/yaml/recurfile
Package recurfile handles loading and validating recurfile YAML documents.
 Package recurfile handles loading and validating recurfile YAML documents.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.