icaru

A command-line iCal calendar viewer and syncer written in Rust.

Features

• View today's, this week's, this month's, or upcoming N days' events
• Recurring event support: Automatically expands RRULE-based recurring events within the requested date range
• Color-coded output: Each calendar can be assigned a terminal color for quick visual identification
• Local timezone display: Event times are converted to your system's local timezone
• Sync calendars from remote iCal (.ics) URLs
• Support for all-day and timed events

Installation

From crates.io (Recommended)

cargo install icaru

After installation, make sure ~/.cargo/bin is in your PATH, then you can run:

icaru

Prerequisites

• Rust (latest stable version)

Build from source

git clone https://github.com/maedana/icaru.git
cd icaru
cargo build --release

The binary will be available at target/release/icaru.

Configuration

Create ~/.icaru/config.toml:

[[cal]]
file = "work.ics"
name = "Work"
color = "blue"
url = "https://example.com/work.ics"

[[cal]]
file = "personal.ics"
name = "Personal"
color = "green"

Fields

• file — local filename stored under ~/.icaru/
• name — display name shown in output
• color — terminal color (red, green, blue, yellow, magenta, cyan, white)
• url — remote iCal URL (optional; required for pull subcommand)

Usage

# Show today's events (default)
icaru

# Other ranges
icaru this-week
icaru next-month
icaru days 7
icaru date 2026-04-20

# Sync calendars from remote URLs
icaru pull

Example output:

2026-04-13 (Mon)
  09:00-10:00   [Work]  Weekly MTG
  12:30         [Work]  Lunch with team
2026-04-14 (Tue)
  All day       [Personal]  Dentist

See icaru -h for the full list of subcommands and options.

Development

Running in Development

cargo run

Running Tests

cargo test

Code Quality

cargo clippy
cargo fmt

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request