> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-cal

> Print a month grid and agenda list to stdout. Works with bar clock popovers and plain-text agenda files.

otter-cal powers the calendar popover on Otter Shell's status bar clock. It prints a month grid and a bounded agenda list to stdout. Left-click the clock widget and that output shows up as a popover. Today's date uses your theme accent color. Pipe it into any bar or launcher that displays text, or run it in a terminal.

## Usage

```bash theme={null}
otter-cal                                              # current month
otter-cal --month 2026-06                              # specific month
otter-cal --today 2026-06-05 --agenda ~/.config/otter-shell/agenda  # with agenda file
otter-cal --next 1                                     # next month
```

## Agenda File Format

Each line has a date in `YYYY-MM-DD` format, a space, and the event description. One event per line:

```text theme={null}
2026-06-15 Team retrospective
2026-06-20 Release day
```

Pass the file path with `--agenda`, or set `agenda_path` in the config file.

## Bar Integration

The Otter Shell status bar clock runs a command on left-click. The default is `otter-cal`, which opens the calendar popover inline. Override it with `clock_calendar_command` in your bar configuration:

```conf theme={null}
clock_calendar_command = "otter-cal"
```

Replace the value with any command whose stdout the bar should display. A wrapper script that passes a custom `--agenda` path works fine.

## Configuration

otter-cal reads `~/.config/otter-shell/otter-cal.conf`:

```conf theme={null}
agenda_path = ""
```

* `agenda_path`: absolute path to your agenda file. Empty runs without agenda data.