rcal Public

Watch 0 Fork 0 Star 0

markdown · 3230 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 the Create event modal.
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 modal supports timed events, single-day all-day events, 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.
Editing or deleting existing events is 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 the Create event modal.
      
        53
        - `Enter` opens the focused day view.
      
        54
        - `Esc` returns from day view to month view.
      
        55
        - `q` exits.
      
        56
        - In day view, Left/Right move to the previous or next day while staying in day
      
        57
          view.
      
        58
        - Digits jump immediately to a day in the visible month. A quick second digit
      
        59
          refines the selected day, so `1` selects day 1 and `1` then `6` selects day
      
        60
          16.
      
        61
        - Weekday initials jump within the selected week. Use `tu` for Tuesday, `th`
      
        62
          for Thursday, `su` for Sunday, and `sa` for Saturday.
      
        63
        - Left click selects a visible date; left click the selected date again to open
      
        64
          day view.
      
        65
        
        66
        Created events are stored locally as JSON and are shown immediately in month,
      
        67
        week, and day views. The create modal supports timed events, single-day all-day
      
        68
        events, location, notes, and multiple reminder offsets; reminder notifications
      
        69
        are not delivered yet.
      
        70
        
        71
        ## Layout
      
        72
        
        73
        `rcal` tries to render the full month first. If the terminal is too constrained,
      
        74
        it falls back to the selected week. If even that cannot fit cleanly, it falls
      
        75
        back to a focused day summary.
      
        76
        
        77
        ## Current Limits
      
        78
        
        79
        - Real account integrations for Outlook, Google Calendar, Exchange, and similar
      
        80
          providers are not implemented yet.
      
        81
        - Editing or deleting existing events is not implemented yet.
      
        82
        - Reminder offsets are stored but do not trigger notifications yet.
      
        83
        - Packaging is currently source-based through Cargo.
      
        84
        
        85
        ## Development
      
        86
        
        87
        CI runs the same core commands used locally:
      
        88
        
        89
        ```sh
      
        90
        cargo fmt --all -- --check
      
        91
        cargo clippy --all-targets --all-features -- -D warnings
      
        92
        cargo test --all-targets --all-features
      
        93
        ```
      
        94
        
        95
        The project intentionally keeps private planning notes under `.docs/`; they are
      
        96
        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 the Create event modal.
53	- `Enter` opens the focused day view.
54	- `Esc` returns from day view to month view.
55	- `q` exits.
56	- In day view, Left/Right move to the previous or next day while staying in day
57	view.
58	- Digits jump immediately to a day in the visible month. A quick second digit
59	refines the selected day, so `1` selects day 1 and `1` then `6` selects day
60	16.
61	- Weekday initials jump within the selected week. Use `tu` for Tuesday, `th`
62	for Thursday, `su` for Sunday, and `sa` for Saturday.
63	- Left click selects a visible date; left click the selected date again to open
64	day view.
65
66	Created events are stored locally as JSON and are shown immediately in month,
67	week, and day views. The create modal supports timed events, single-day all-day
68	events, location, notes, and multiple reminder offsets; reminder notifications
69	are not delivered yet.
70
71	## Layout
72
73	`rcal` tries to render the full month first. If the terminal is too constrained,
74	it falls back to the selected week. If even that cannot fit cleanly, it falls
75	back to a focused day summary.
76
77	## Current Limits
78
79	- Real account integrations for Outlook, Google Calendar, Exchange, and similar
80	providers are not implemented yet.
81	- Editing or deleting existing events is not implemented yet.
82	- Reminder offsets are stored but do not trigger notifications yet.
83	- Packaging is currently source-based through Cargo.
84
85	## Development
86
87	CI runs the same core commands used locally:
88
89	```sh
90	cargo fmt --all -- --check
91	cargo clippy --all-targets --all-features -- -D warnings
92	cargo test --all-targets --all-features
93	```
94
95	The project intentionally keeps private planning notes under `.docs/`; they are
96	not part of the tracked release surface.