rcal Public

Watch 0 Fork 0 Star 0

markdown · 3293 bytes Raw Blame History

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.

This first milestone is meant for local daily trial use. It opens on the current month, keeps keyboard navigation fast, falls back to week or day views when terminal space is tight, and shows agenda previews from the current local events file plus holiday sources.

Install

From a checkout of this repository:

cargo install --path .

For development:

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

Usage

rcal [--date YYYY-MM-DD] [--events-file PATH] [--holiday-source off|us-federal|nager] [--holiday-country CC]

Options:

--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.

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, d opens the Delete confirmation for the selected local 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; left click the selected date again to open day view.

Created events are stored locally as JSON and are shown immediately in month, week, and day views. The create/edit modal supports timed events, single-day all-day events, recurrence, location, notes, and multiple reminder offsets. Reminder notifications are not delivered yet.

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.

Current Limits

Real account integrations for Outlook, Google Calendar, Exchange, and similar providers are not implemented yet.
Reminder offsets are stored but do not trigger notifications yet.
Packaging is currently source-based through Cargo.

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.

View source

  
        1
        # rcal
      
        2
        
        3
        `rcal` is a terminal calendar for quick month, week, and day navigation. It is
      
        4
        built in Rust with `ratatui`, `crossterm`, and the `time` crate.
      
        5
        
        6
        This first milestone is meant for local daily trial use. It opens on the
      
        7
        current month, keeps keyboard navigation fast, falls back to week or day views
      
        8
        when terminal space is tight, and shows agenda previews from the current local
      
        9
        events file plus holiday sources.
      
        10
        
        11
        ## Install
      
        12
        
        13
        From a checkout of this repository:
      
        14
        
        15
        ```sh
      
        16
        cargo install --path .
      
        17
        ```
      
        18
        
        19
        For development:
      
        20
        
        21
        ```sh
      
        22
        cargo run -- --date 2026-04-23
      
        23
        ```
      
        24
        
        25
        ## Usage
      
        26
        
        27
        ```sh
      
        28
        rcal [--date YYYY-MM-DD] [--events-file PATH] [--holiday-source off|us-federal|nager] [--holiday-country CC]
      
        29
        ```
      
        30
        
        31
        Options:
      
        32
        
        33
        - `--date YYYY-MM-DD`: open with a deterministic selected date.
      
        34
        - `--events-file PATH`: read and write local user-created events at `PATH`.
      
        35
          By default, rcal uses `$XDG_DATA_HOME/rcal/events.json`,
      
        36
          `$HOME/.local/share/rcal/events.json`, or a temp fallback.
      
        37
        - `--holiday-source us-federal`: use offline U.S. federal holidays. This is the
      
        38
          default.
      
        39
        - `--holiday-source off`: disable holiday rendering.
      
        40
        - `--holiday-source nager`: fetch public holidays from Nager.Date on demand.
      
        41
        - `--holiday-country CC`: two-letter country code for Nager.Date. This option
      
        42
          requires `--holiday-source nager`; default is `US`.
      
        43
        - `--help`: show CLI help.
      
        44
        - `--version`: show the installed version.
      
        45
        
        46
        Nager.Date is cache-first and opt-in. Default startup does not need network
      
        47
        access.
      
        48
        
        49
        ## Controls
      
        50
        
        51
        - Arrow keys move the selected date.
      
        52
        - `?` opens contextual help.
      
        53
        - `+` opens the Create event modal.
      
        54
        - In day view, `d` opens the Delete confirmation for the selected local event.
      
        55
        - `Enter` opens the focused day view.
      
        56
        - `Esc` returns from day view to month view.
      
        57
        - `q` exits.
      
        58
        - In day view, Left/Right move to the previous or next day while staying in day
      
        59
          view.
      
        60
        - Digits jump immediately to a day in the visible month. A quick second digit
      
        61
          refines the selected day, so `1` selects day 1 and `1` then `6` selects day
      
        62
          16.
      
        63
        - Weekday initials jump within the selected week. Use `tu` for Tuesday, `th`
      
        64
          for Thursday, `su` for Sunday, and `sa` for Saturday.
      
        65
        - Left click selects a visible date; left click the selected date again to open
      
        66
          day view.
      
        67
        
        68
        Created events are stored locally as JSON and are shown immediately in month,
      
        69
        week, and day views. The create/edit modal supports timed events, single-day
      
        70
        all-day events, recurrence, location, notes, and multiple reminder offsets.
      
        71
        Reminder notifications are not delivered yet.
      
        72
        
        73
        ## Layout
      
        74
        
        75
        `rcal` tries to render the full month first. If the terminal is too constrained,
      
        76
        it falls back to the selected week. If even that cannot fit cleanly, it falls
      
        77
        back to a focused day summary.
      
        78
        
        79
        ## Current Limits
      
        80
        
        81
        - Real account integrations for Outlook, Google Calendar, Exchange, and similar
      
        82
          providers are not implemented yet.
      
        83
        - Reminder offsets are stored but do not trigger notifications yet.
      
        84
        - Packaging is currently source-based through Cargo.
      
        85
        
        86
        ## Development
      
        87
        
        88
        CI runs the same core commands used locally:
      
        89
        
        90
        ```sh
      
        91
        cargo fmt --all -- --check
      
        92
        cargo clippy --all-targets --all-features -- -D warnings
      
        93
        cargo test --all-targets --all-features
      
        94
        ```
      
        95
        
        96
        The project intentionally keeps private planning notes under `.docs/`; they are
      
        97
        not part of the tracked release surface.

1	# rcal
2
3	`rcal` is a terminal calendar for quick month, week, and day navigation. It is
4	built in Rust with `ratatui`, `crossterm`, and the `time` crate.
5
6	This first milestone is meant for local daily trial use. It opens on the
7	current month, keeps keyboard navigation fast, falls back to week or day views
8	when terminal space is tight, and shows agenda previews from the current local
9	events file plus holiday sources.
10
11	## Install
12
13	From a checkout of this repository:
14
15	```sh
16	cargo install --path .
17	```
18
19	For development:
20
21	```sh
22	cargo run -- --date 2026-04-23
23	```
24
25	## Usage
26
27	```sh
28	rcal [--date YYYY-MM-DD] [--events-file PATH] [--holiday-source off\|us-federal\|nager] [--holiday-country CC]
29	```
30
31	Options:
32
33	- `--date YYYY-MM-DD`: open with a deterministic selected date.
34	- `--events-file PATH`: read and write local user-created events at `PATH`.
35	By default, rcal uses `$XDG_DATA_HOME/rcal/events.json`,
36	`$HOME/.local/share/rcal/events.json`, or a temp fallback.
37	- `--holiday-source us-federal`: use offline U.S. federal holidays. This is the
38	default.
39	- `--holiday-source off`: disable holiday rendering.
40	- `--holiday-source nager`: fetch public holidays from Nager.Date on demand.
41	- `--holiday-country CC`: two-letter country code for Nager.Date. This option
42	requires `--holiday-source nager`; default is `US`.
43	- `--help`: show CLI help.
44	- `--version`: show the installed version.
45
46	Nager.Date is cache-first and opt-in. Default startup does not need network
47	access.
48
49	## Controls
50
51	- Arrow keys move the selected date.
52	- `?` opens contextual help.
53	- `+` opens the Create event modal.
54	- In day view, `d` opens the Delete confirmation for the selected local event.
55	- `Enter` opens the focused day view.
56	- `Esc` returns from day view to month view.
57	- `q` exits.
58	- In day view, Left/Right move to the previous or next day while staying in day
59	view.
60	- Digits jump immediately to a day in the visible month. A quick second digit
61	refines the selected day, so `1` selects day 1 and `1` then `6` selects day
62	16.
63	- Weekday initials jump within the selected week. Use `tu` for Tuesday, `th`
64	for Thursday, `su` for Sunday, and `sa` for Saturday.
65	- Left click selects a visible date; left click the selected date again to open
66	day view.
67
68	Created events are stored locally as JSON and are shown immediately in month,
69	week, and day views. The create/edit modal supports timed events, single-day
70	all-day events, recurrence, location, notes, and multiple reminder offsets.
71	Reminder notifications are not delivered yet.
72
73	## Layout
74
75	`rcal` tries to render the full month first. If the terminal is too constrained,
76	it falls back to the selected week. If even that cannot fit cleanly, it falls
77	back to a focused day summary.
78
79	## Current Limits
80
81	- Real account integrations for Outlook, Google Calendar, Exchange, and similar
82	providers are not implemented yet.
83	- Reminder offsets are stored but do not trigger notifications yet.
84	- Packaging is currently source-based through Cargo.
85
86	## Development
87
88	CI runs the same core commands used locally:
89
90	```sh
91	cargo fmt --all -- --check
92	cargo clippy --all-targets --all-features -- -D warnings
93	cargo test --all-targets --all-features
94	```
95
96	The project intentionally keeps private planning notes under `.docs/`; they are
97	not part of the tracked release surface.