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
@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.
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.
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
- Node.js 24+
npm install -g @rrulenet/cli
rrulenet --helprrulenet --help
rrulenet local add "FREQ=DAILY;BYHOUR=9;BYMINUTE=0;BYSECOND=0" -- echo "sync"
rrulenet local list
rrulenet listLocal data is stored in ./.rrulenet relative to your current working directory.
Override with:
RRULENET_DATA_DIR=/path/to/data rrulenet local listAn 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 syncDurations 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.
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 listCloud 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/hookInspect 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 abcd1234Use --offset with cloud list and cloud executions for pagination. Add
--json to any cloud command for machine-readable output.
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.
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:
launchdon macOSsystemd --useron Linux
The generated service writes logs in RRULENET_DATA_DIR:
rrulenet-runner.out.logrrulenet-runner.err.log
Generate a plist:
rrulenet local service print --target launchd > ~/Library/LaunchAgents/net.rrule.local-runner.plistLoad 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-runnerStop it:
launchctl stop net.rrule.local-runner
launchctl unload ~/Library/LaunchAgents/net.rrule.local-runner.plistCheck logs:
tail -f ./.rrulenet/rrulenet-runner.out.log
tail -f ./.rrulenet/rrulenet-runner.err.logIf you use a custom data directory, generate the template with:
rrulenet local service print --target launchd --data-dir /path/to/dataGenerate a unit:
mkdir -p ~/.config/systemd/user
rrulenet local service print --target systemd-user > ~/.config/systemd/user/rrulenet-local-runner.serviceReload and start it:
systemctl --user daemon-reload
systemctl --user enable --now rrulenet-local-runnerStop it:
systemctl --user disable --now rrulenet-local-runnerCheck 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.logTo change the polling interval or binary path:
rrulenet local service print --target systemd-user --interval-ms 10000 --bin /absolute/path/to/rrulenetFor 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 --helpThe 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 listThis suppresses ExperimentalWarning messages for the Node process. We do not
recommend using broader flags such as --no-warnings.
MIT
This license applies to the CLI source code in this repository only. Hosted
rrule.net services and APIs are governed separately.