Skip to content
rrulenetPublic

About

Command-line workflows for recurring jobs, local schedulers, and rrule.net cloud schedules.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

rrule.net

@rrulenet/cli

Command-line workflows for recurring jobs, local schedulers, and rrule.net cloud schedules.

rrule.net • Temporal API • @rrulenet ecosystem

@rrulenet/rrule · @rrulenet/recurrence · @rrulenet/core · @rrulenet/cli

npm version Coverage MIT License

@rrulenet/rrule: classic API · @rrulenet/recurrence: Temporal-first API · @rrulenet/core: engine · @rrulenet/cli: workflows

@rrulenet/cli provides the command-line interface in the ecosystem. It is designed for teams that want to run recurring jobs locally, operate a persistent local scheduler, and work with rrule.net cloud schedules from the same tool.

Use @rrulenet/cli when you want operational workflows around schedules. Use @rrulenet/rrule or @rrulenet/recurrence when you want to embed recurrence logic directly in application code.

Why this exists

Recurring schedules seem simple until real-world constraints appear:

  • timezones and DST
  • long-running schedules
  • end-of-month and leap-year edge cases
  • reliability over time

rrulenet provides calendar rules and fixed-duration cadences for local execution, alongside cloud-managed schedules.

What this CLI does

Use rrulenet to:

  • run local recurring jobs from the command line
  • run a persistent local scheduler on your machine
  • create and manage cloud schedules on rrule.net
  • inspect cloud schedule details and recent execution history

Requirements

  • Node.js 24+

Installation

npm install -g @rrulenet/cli
rrulenet --help

Quick start

rrulenet --help
rrulenet local add "FREQ=DAILY;BYHOUR=9;BYMINUTE=0;BYSECOND=0" -- echo "sync"
rrulenet local list
rrulenet list

Local data is stored in ./.rrulenet relative to your current working directory. Override with:

RRULENET_DATA_DIR=/path/to/data rrulenet local list

Calendar and elapsed local schedules (0.2.0)

An RRULE uses the local calendar clock: the first autumn passage, and spring resolution using the pre-transition offset. To request a fixed elapsed cadence, use --elapsed instead of the positional RRULE:

rrulenet simulate --elapsed PT30M --dtstart 2026-10-24T23:30:00Z --timezone Europe/Paris --count 6 --json
rrulenet local add --elapsed PT30M --dtstart 2026-10-24T23:30:00Z -- echo sync

Durations use ISO 8601 notation: P starts the duration, and T introduces the hours/minutes/seconds part.

Duration Meaning
PT5S 5 seconds
PT1M 1 minute
PT30M 30 minutes
PT1H30M 1 hour and 30 minutes
PT24H Exactly 24 elapsed hours

P1M means one calendar month, whereas PT1M means one minute. --elapsed and --adopt-elapsed accept only positive time durations totaling whole seconds. Calendar units such as P1D (one day) or P1M (one month) are rejected. Use PT24H for exactly 24 elapsed hours; a local calendar day can span 23 or 25 hours across a DST transition.

The exact anchor is persisted and is retained through completion, pause, and resume. The local CLI accepts timestamps at millisecond precision; finer input is rejected rather than truncated by the SQLite runner. The library API retains nanosecond precision. SQLite stores versioned native recurrence JSON in recurrence_json; the rrule column remains a human-readable input label for elapsed schedules.

Existing local schedules require explicit adoption before they can run with 0.2.0. Stop runners and back up the local store before upgrading. Follow the migration guide for calendar or elapsed adoption, before/after checks, test rehearsals, and rollback instructions. Hosted migration is separate.

Cloud setup

rrulenet config set cloud.api_url https://api.rrule.net
rrulenet config set cloud.token <your_api_key_or_token>
RRULENET_TOKEN=<your_api_key_or_token> rrulenet cloud list

Cloud schedule input can be an RRULE, a cron expression, or natural language:

rrulenet cloud add "every weekday at 09:00" \
  --timezone Europe/Paris \
  --webhook https://example.com/hook

Inspect and operate schedules with either a full id or a unique id prefix:

rrulenet cloud list --status active --limit 25
rrulenet cloud get abcd1234
rrulenet cloud executions abcd1234 --limit 25
rrulenet cloud pause abcd1234
rrulenet cloud resume abcd1234
rrulenet cloud remove abcd1234

Use --offset with cloud list and cloud executions for pagination. Add --json to any cloud command for machine-readable output.

Local and cloud

The CLI supports both local execution and cloud schedule management.

Capability Local CLI rrule.net cloud
RRULE, cron, and natural-language input RRULE locally ✅
Local command execution ✅ ❌
Persistent background runner ✅ ✅ managed
Cloud-managed schedules ❌ ✅
API-backed schedule operations via cloud commands ✅

Use the CLI to build, test, and run schedules locally.

Use rrule.net when you want managed cloud execution and API-backed schedule operations.

Run as a background service

rrulenet local run can be managed by a user-level service manager. The CLI does not install services automatically, but it can generate a template for:

  • launchd on macOS
  • systemd --user on Linux

The generated service writes logs in RRULENET_DATA_DIR:

  • rrulenet-runner.out.log
  • rrulenet-runner.err.log

macOS (launchd)

Generate a plist:

rrulenet local service print --target launchd > ~/Library/LaunchAgents/net.rrule.local-runner.plist

Load and start it:

launchctl unload ~/Library/LaunchAgents/net.rrule.local-runner.plist 2>/dev/null
launchctl load ~/Library/LaunchAgents/net.rrule.local-runner.plist
launchctl start net.rrule.local-runner

Stop it:

launchctl stop net.rrule.local-runner
launchctl unload ~/Library/LaunchAgents/net.rrule.local-runner.plist

Check logs:

tail -f ./.rrulenet/rrulenet-runner.out.log
tail -f ./.rrulenet/rrulenet-runner.err.log

If you use a custom data directory, generate the template with:

rrulenet local service print --target launchd --data-dir /path/to/data

Linux (systemd --user)

Generate a unit:

mkdir -p ~/.config/systemd/user
rrulenet local service print --target systemd-user > ~/.config/systemd/user/rrulenet-local-runner.service

Reload and start it:

systemctl --user daemon-reload
systemctl --user enable --now rrulenet-local-runner

Stop it:

systemctl --user disable --now rrulenet-local-runner

Check status and logs:

systemctl --user status rrulenet-local-runner
journalctl --user -u rrulenet-local-runner -f
tail -f ./.rrulenet/rrulenet-runner.out.log
tail -f ./.rrulenet/rrulenet-runner.err.log

To change the polling interval or binary path:

rrulenet local service print --target systemd-user --interval-ms 10000 --bin /absolute/path/to/rrulenet

Dev

For development, npm link exposes the global rrulenet binary from your local checkout without a separate global install:

cd cli
npm install
npm run build
npm link
rrulenet --help

Notes

The local scheduler uses Node's native node:sqlite module.

On current Node 24+ releases, node:sqlite does not require the old --experimental-sqlite flag anymore. Node may still print an ExperimentalWarning when the module is loaded.

If you want to hide that warning when running the CLI, use:

NODE_OPTIONS=--disable-warning=ExperimentalWarning rrulenet local list

This suppresses ExperimentalWarning messages for the Node process. We do not recommend using broader flags such as --no-warnings.

License

MIT

This license applies to the CLI source code in this repository only. Hosted rrule.net services and APIs are governed separately.

About

Command-line workflows for recurring jobs, local schedulers, and rrule.net cloud schedules.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages