rcal

rcal is a terminal calendar for quick month, week, and day navigation. It is built in Rust with ratatui, crossterm, and the time crate.

Install

From a checkout of this repository:

cargo install --path .

For development:

cargo run -- --date 2026-04-23

Usage

rcal [--config PATH|--no-config] [--date YYYY-MM-DD] [--events-file PATH] [--holiday-source off|us-federal|nager] [--holiday-country CC]
rcal config init [--path PATH] [--force]
rcal providers microsoft auth login --account ID [--browser]
rcal providers microsoft auth logout --account ID
rcal providers microsoft auth inspect --account ID
rcal providers microsoft calendars list --account ID
rcal providers microsoft setup --account ID [--browser] [--calendar ID]
rcal providers microsoft sync [--account ID]
rcal providers microsoft status
rcal providers google auth login --account ID
rcal providers google auth logout --account ID
rcal providers google auth inspect --account ID
rcal providers google calendars list --account ID
rcal providers google setup --account ID [--client-id ID] [--client-secret SECRET] [--calendar ID]
rcal providers google sync [--account ID]
rcal providers google status
rcal reminders run [--events-file PATH] [--state-file PATH] [--once]
rcal reminders install [--events-file PATH] [--state-file PATH]
rcal reminders uninstall
rcal reminders status
rcal reminders test [--verbose]

Options:

• --config PATH: load a specific TOML config file.
• --no-config: ignore any discovered config file.
• --date YYYY-MM-DD: open with a deterministic selected date.
• --events-file PATH: read and write local user-created events at PATH. By default, rcal uses $XDG_DATA_HOME/rcal/events.json, $HOME/.local/share/rcal/events.json, or a temp fallback.
• --holiday-source us-federal: use offline U.S. federal holidays. This is the default.
• --holiday-source off: disable holiday rendering.
• --holiday-source nager: fetch public holidays from Nager.Date on demand.
• --holiday-country CC: two-letter country code for Nager.Date. This option requires --holiday-source nager; default is US.
• --help: show CLI help.
• --version: show the installed version.

Config is discovered at $XDG_CONFIG_HOME/rcal/config.toml, else ~/.config/rcal/config.toml. It is never created automatically; run rcal config init to write a commented starter file. Omitted settings keep built-in defaults, and CLI flags override config values. Config can set the events file, holiday source and country, reminder state file, and normal-mode keybindings. It can also configure the Microsoft and Google Calendar providers. Modal/form keys stay fixed for now.

Nager.Date is cache-first and opt-in. Default startup does not need network access.

Controls

• Arrow keys move the selected date.
• ? opens contextual help.
• + opens the Create event modal.
• In day view, c opens the Copy confirmation for the selected editable event.
• In day view, d opens the Delete confirmation for the selected editable event.
• Enter opens the focused day view.
• Esc returns from day view to month view.
• q exits.
• In day view, Left/Right move to the previous or next day while staying in day view.
• Digits jump immediately to a day in the visible month. A quick second digit refines the selected day, so 1 selects day 1 and 1 then 6 selects day 16.
• Weekday initials jump within the selected week. Use tu for Tuesday, th for Thursday, su for Sunday, and sa for Saturday.
• Left click selects a visible date; double-click a visible date to open day view.

The create/edit modal supports timed events, single-day all-day events, recurrence, location, notes, and multiple reminder offsets. Its Calendar field controls where the event is saved; use Left/Right on that field to cycle between local storage and configured editable provider calendars. Local events are stored as JSON, while provider events are written through their remote API and then shown immediately from the provider cache. Reminder notifications are delivered by a user-level background service. Use rcal reminders install to install it, rcal reminders status to inspect it, and rcal reminders test to send a test notification. On macOS, notification delivery uses osascript because it is more reliable for CLI-launched notifications than the generic notification backend. Reminder install snapshots the resolved events and state file paths, so reinstall the service after config changes that affect reminders.

Layout

rcal tries to render the full month first. If the terminal is too constrained, it falls back to the selected week. If even that cannot fit cleanly, it falls back to a focused day summary.

Microsoft Provider

Microsoft Graph is the first remote provider. It is cache-first: the TUI reads the local Microsoft cache instantly, and you refresh remote data explicitly:

rcal providers microsoft setup --account work --browser
rcal

The setup command uses rcal's official public/native Microsoft client ID, opens the Microsoft login flow, selects your default editable calendar, writes ~/.config/rcal/config.toml, performs the first sync, and sets new event creation to Microsoft by default. No client secret is used or stored; rcal stores user tokens in the OS keychain.

Use --calendar CALENDAR_ID if you already know which editable calendar to use. You can list calendars later with:

rcal providers microsoft calendars list --account work

Microsoft Account Setup

The normal setup flow is:

rcal providers microsoft setup --account work --browser
rcal providers microsoft status
rcal

For advanced testing, you may still override the Microsoft app registration in config.toml. Omit client_id and tenant to use rcal's official public app:

[providers]
create_target = "microsoft" # or "local" to keep new events local-only

[providers.microsoft]
enabled = true
default_account = "work"
default_calendar = "CALENDAR_ID"
sync_past_days = 30
sync_future_days = 365

[[providers.microsoft.accounts]]
id = "work"
# client_id = "AZURE_APP_CLIENT_ID"
# tenant = "common"
redirect_port = 8765
calendars = ["CALENDAR_ID"]

Manual sync remains available:

rcal providers microsoft sync --account work

Deprecated manual onboarding flow, pending deletion:

rcal config init
# edit ~/.config/rcal/config.toml with providers.microsoft account/calendar data
rcal providers microsoft auth login --account work --browser
rcal providers microsoft calendars list --account work
# copy an editable calendar ID into default_calendar and calendars
rcal providers microsoft sync --account work

Use rcal providers microsoft setup --account work --browser instead. The manual flow is kept temporarily for advanced custom-app testing and for users upgrading from early provider builds.

Use rcal providers microsoft auth inspect --account work to inspect safe token claims such as audience, scopes, tenant, and expiry. The command does not print the token body.

The provider syncs configured calendars through Graph calendarView, caches selected events separately from the local events JSON, and routes create/edit/delete/copy operations for Microsoft events back through Graph. Provider reminders fire from cached provider events after a sync; the reminder daemon does not sync remote calendars itself.

Google Calendar Provider

Google Calendar support is also cache-first. You refresh remote data explicitly:

rcal providers google setup --account personal
rcal

The setup flow uses rcal's official Google OAuth Desktop client when the build includes one. It opens browser auth, selects your default editable calendar, writes ~/.config/rcal/config.toml, performs the first sync, and sets new event creation to Google by default. User tokens are stored in the OS keychain.

Use --calendar CALENDAR_ID to choose a known editable calendar. You can list calendars later with:

rcal providers google calendars list --account personal

Manual sync:

rcal providers google sync --account personal

Generated Google config looks like:

[providers]
create_target = "google" # or "local" to keep new events local-only

[providers.google]
enabled = true
default_account = "personal"
default_calendar = "primary"
sync_past_days = 30
sync_future_days = 365

[[providers.google.accounts]]
id = "personal"
# client_id = "GOOGLE_CLIENT_ID"         # optional custom OAuth client
# client_secret = "GOOGLE_CLIENT_SECRET" # optional custom OAuth client secret
redirect_port = 8766
calendars = ["primary"]

Advanced custom-client setup remains available for development builds or for users who want their own Google OAuth quota/project:

rcal providers google setup \
  --account personal \
  --client-id GOOGLE_CLIENT_ID \
  --client-secret GOOGLE_CLIENT_SECRET

The Google provider syncs configured calendars through the Calendar API, caches selected events separately from the local events JSON, and routes create/edit/delete/copy operations for Google events back through Google Calendar. Provider reminders fire from cached Google events after a sync.

Current Limits

• CalDAV and other non-Microsoft/non-Google providers are not implemented yet.
• Provider sync is manual and cache-first; there is no background provider sync daemon yet.
• Google OAuth verification may still be in progress for early releases. If the official client flow is unavailable in a custom build, use the advanced custom-client setup above.

Development

CI runs the same core commands used locally:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

The project intentionally keeps private planning notes under .docs/; they are not part of the tracked release surface.