soon

A fast, local-first CLI tool that reads macOS Calendar events and renders them in the terminal

Install

From source

git clone https://github.com/cesarferreira/soon
cd soon
cargo install --path .

Quick start

# Show today's events
soon today

# Show tomorrow's events
soon tomorrow

# Show this week's events (grid view)
soon week

# Show next week's events
soon next week

# Show the next upcoming event with countdown
soon upcoming

Options

# Choose view type
soon today --view grid
soon week --view list

# Output format
soon today --format plain    # No colors
soon today --format json     # JSON output for scripting

# Filter calendars
soon today --cal Work
soon today --cal Work --cal Personal
soon today --exclude-cal "Birthdays"

# Exclude all-day events
soon today --no-all-day

# Custom timezone
soon today --tz "America/New_York"

# Upcoming events within a specific period
soon upcoming --within 14d

Output examples

List view (soon today):

Today, Monday January 13

  09:30 - 10:00 │ Standup              Zoom       [Work]
  10:00 - 11:00 │ Planning             Room 3B    [Work]
        All-day │ PTO                             [Personal]

Upcoming view (soon upcoming):

Planning
10:00 - 11:00  in 20m
📍 Room 3B
[Work]

JSON output

For scripting and integration:

soon today --format json

{
  "range": {
    "label": "Today, Monday January 13",
    "start": "2025-01-13T00:00:00-08:00",
    "end": "2025-01-13T23:59:59-08:00"
  },
  "events": [
    {
      "id": "abc123",
      "title": "Standup",
      "start": "2025-01-13T09:30:00-08:00",
      "end": "2025-01-13T10:00:00-08:00",
      "is_all_day": false,
      "location": "Zoom",
      "calendar": "Work"
    }
  ],
  "count": 1
}

Shell completions

Generate shell completions:

# Bash
soon completions bash > ~/.local/share/bash-completion/completions/soon

# Zsh
soon completions zsh > ~/.zfunc/_soon

# Fish
soon completions fish > ~/.config/fish/completions/soon.fish

Requirements

• macOS (uses native EventKit framework)
• Rust 1.70+

Calendar access

On first run, soon requests access to your calendars.

Grant access in System Settings > Privacy & Security > Calendars for soon or your terminal application.

Exit codes

Code	Meaning
0	Success
1	Generic failure
2	Invalid arguments
3	Calendar access denied
4	No calendars/events found

Development

# Run in development
cargo run -- today

# Run tests
cargo test

# Build release
cargo build --release

License

MIT. See LICENSE.