5 releases

0.0.3 May 18, 2023
0.0.2 May 15, 2023
0.0.1 Jan 1, 2022
0.0.1-alpha.2 Dec 12, 2021
0.0.1-alpha.1 Dec 11, 2021

#44 in Date and time

Download history 7/week @ 2023-02-09 5/week @ 2023-02-16 1/week @ 2023-02-23 1/week @ 2023-03-02 7/week @ 2023-03-16 1/week @ 2023-03-23 22/week @ 2023-04-06 1/week @ 2023-04-13 6/week @ 2023-05-04 25/week @ 2023-05-11 39/week @ 2023-05-18 15/week @ 2023-05-25

85 downloads per month

MIT license



carl logo

carl is a calendar for the commandline. It tries to mimic the various cal(1) implementations out there, but also adds enhanced features like colors and ical support.

This is still alpha software. There are certainly bugs included and features missing, so please don't hesitate to create a bug report or a feature request.

Default output of carl

carl output with custom colors

carl output with events
from ical highlighted

Screenshots of default carl

Screenshot of carl with custom colors

Screenshot of carl with ical events highlighted


cargo install carl

Commandline flags

  • -1, --one: Display single month output. (This is the default.)
  • -3, --three: Display prev/current/next month output.
  • -s, --sunday: Display Sunday as the first day of the week.
  • -m, --monday: Display Monday as the first day of the week.
  • -j, --julian: Display Julian dates (days one-based, numbered from January 1).
  • -y, --year: Display a calendar for the current year.
  • -V, --version: Display version information and exit.
  • -h, --help: Display help screen and exit.
  • --theme: Set the theme that should be used
  • --themestyletype: "dark" or "light", use the theme styles marked for "dark" or for "light" backgrounds. Defaults to "light"

Commandline options

  • YYYY: Display the current date from the given year
  • MM YYYYY: Display the given month in the given year
  • DD MM YYYY: Display the given date

Configuration file

The configuration file is located XDG_CONFIG_DIRS/carl/config.toml or XDG_CONFIG_HOME/.carl/config.toml (the latter has precedence).

The configuration file can define the name of a themefile and multiple icalfiles. Themefiles contain listings of date properties together with styledefintions. Icalfile listings contain paths to icalfiles together with styledefinitions.

The name of a them is simple specified using the theme = setting:

theme = "default"

The themefile is read from XDG_CONFIG_DIRS/carl/<themename>.toml or XDG_CONFIG_HOME/.carl/<themename>.toml (the latter has precedence).

Icalfiles can be specified using the [[ical]] setting:

file = "/home/user/birthdays.ics"
stylenames = ['FGPurple']

If the file setting points to a directory, carl uses all the files in that directory it can parse.

A sample configuration file is located in data/config.toml.


Themefiles and Icalfile listings can contain custom style settings. A style changes how a specific date in the calendar is displayed. A style consists of a list of stylenames and optionally a weight and a styletype ('Dark' or 'Light'). If no styletype is set, the style is effective in either case. The various possible stylenames are listed at the bottom.


stylenames = ['Dimmed']
weight = 10
styletype = 'Dark'


A themefile consists of a collection of datestyles:


A datestyle consists of a list of properties of a date and a style. The date has to fullfill all of the properties for the style to be applied.


properties = ['CurrentDate']
stylenames = ['FGRed']
weight = 3
styletype = 'Light'

Possible properties

  • FirstDayOfMonth:
  • BeforeFirstDayOfMonth:
  • BeforeCurrentDate:
  • CurrentDate:
  • AfterCurrentDate:
  • AfterLastDayOfMonth:
  • LastDayOfMonth:
  • IsEvent:

A sample theme file is located in data/theme.toml.



  • Bold
  • Dimmed
  • Italic
  • Underline
  • Blink
  • Reverse
  • Hidden
  • Strikethrough

Foreground color names

  • FGBlack
  • FGRed
  • FGGreen
  • FGYellow
  • FGBlue
  • FGPurple
  • FGCyan
  • FGWhite
  • { FGRGB = {r = x, g = y, b = z }} where x, y and z are the RGB values
  • { FGFixed = x } a color number from 0 to 255, see the color chart

Background color names

  • BGBlack
  • BGRed
  • BGGreen
  • BGYellow
  • BGBlue
  • BGPurple
  • BGCyan
  • BGWhite
  • {BGRGB = { r = x, g = y, b = z }} where x, y and z are the RGB values
  • {BGFixed = x } a color number from 0 to 255, see the color chart

Multiple styles and colors can be combined using lists: ["Bold", "FGRed", "Underline"]


~136K SLoC