{"id":15659502,"url":"https://github.com/erikh/saturn","last_synced_at":"2026-03-05T08:32:48.340Z","repository":{"id":186450239,"uuid":"675194586","full_name":"erikh/saturn","owner":"erikh","description":"A calendar for CLI nerds","archived":false,"fork":false,"pushed_at":"2024-03-08T14:34:12.000Z","size":831,"stargazers_count":24,"open_issues_count":19,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-11-07T08:24:10.954Z","etag":null,"topics":["calendar","cli","rust-lang"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erikh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-06T05:12:44.000Z","updated_at":"2025-03-15T09:44:06.000Z","dependencies_parsed_at":"2023-09-26T21:06:22.882Z","dependency_job_id":"596c527b-7800-47a8-90b6-a8ddc1163285","html_url":"https://github.com/erikh/saturn","commit_stats":null,"previous_names":["erikh/saturn"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/erikh/saturn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fsaturn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fsaturn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fsaturn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fsaturn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erikh","download_url":"https://codeload.github.com/erikh/saturn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fsaturn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30115942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T08:19:04.902Z","status":"ssl_error","status_checked_at":"2026-03-05T08:17:37.148Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","cli","rust-lang"],"created_at":"2024-10-03T13:17:10.706Z","updated_at":"2026-03-05T08:32:48.308Z","avatar_url":"https://github.com/erikh.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# saturn: a calendar for CLI nerds\n\n**NOTE:** all docs here chase the `main` branch features. If you want docs for a specific version, go to the `README` for the appropriate tag.\n\n## Special note about the status of this project\n\nUntil this notice is removed, this project is on temporary hiatus. There are a number of design flaws with this program that I need to rectify; I use it daily but there are a lot of things I haven't had the time to address as I have other pressing matters. Once I come back to this, I plan to address these issue in a lump sum and release a new version. I am [cataloguing the issues](ISSUES.md) and you are welcome to follow along. Some of them are very systemic and will take some time to rectify.\n\n## Description\n\nIf you like the application, come to the issues list and voice your ideas and concerns. I have personally been using `saturn` and `sui` for some time alongside Google Calendar (for more complicated situations) with few issues outside of things that happen when developing software normally.\n\nSaturn provides you with a CLI interface to calendaring much in the way [taskwarrior](https://github.com/GothenburgBitFactory/taskwarrior) does with tasks. It also provides you with several methods to query and notify yourself of important appointments. It can act standalone or integrate fully with Google Calendar.\n\n[Here](https://asciinema.org/a/611459) is a short tour (via asciicast) of `saturn` and `sui` in the terminal.\n\nSaturn is also now providing a TUI as a separate program since release v0.2.0; `sui` will present a calendar in a terminal window and allow you to interact with it in similar ways to `saturn`. See below for the list of commands.\n\nHere is what it looks like:\n\n\u003cimg src=\"tui.png\"/\u003e\n\n# Table of Contents\n\n-   [Installation](#installation)\n    -   [Cargo](#cargo)\n    -   [System Packages](#system-packages)\n-   [Entry language](#entry-language)\n    -   [Formats](#formats)\n        -   [Dates](#dates)\n        -   [Times](#times)\n        -   [Durations](#durations)\n-   [Querying](#querying)\n    -   [Listing](#listing)\n    -   [Notifying](#notifying)\n    -   [Editing](#editing)\n    -   [Deletion and Mutation](#deletion-and-mutation)\n    -   [Search](#search)\n-   [Database \u0026amp; Configuration File](#database--configuration-file)\n-   [Leveraging the well features with a periodic scheduler](#leveraging-the-well-features-with-a-periodic-scheduler)\n-   [Recurring tasks](#recurring-tasks)\n-   [Google Calendar Support](#google-calendar-support)\n-   [TUI Commands](#tui-commands)\n-   [Target Platform](#target-platform)\n-   [Author](#author)\n\n## Installation\n\n### Cargo\n\nInstall with cargo:\n\n```\ncargo install saturn-cli\n```\n\nTrack development with:\n\n```\ncargo install --git https://github.com/erikh/saturn\n```\n\n### System Packages\n\nOn NetBSD a pre-compiled package is available from the official repositories. To install it, simply run:\n\n```\npkgin install saturn-cli\n```\n\nRPM and DEB format packages are usually shipped with the [GitHub Releases](https://github.com/erikh/saturn/releases).\n\n## Entry language\n\nEntry language is basically:\n\n```\nENTRY = [ \"recur\" \u003cduration\u003e ] \u003cdate\u003e \u003cAT | SCHEDULED | ALL DAY\u003e [\"notify\" \u003cduration\u003e] \u003cdetail\u003e\nAT = at \u003ctime\u003e\nSCHEDULED = from \u003ctime\u003e to \u003ctime\u003e\nALL DAY = all day\n```\n\nYou trigger it by using `saturn entry`:\n\n```\nsaturn entry tomorrow at 8pm Take a Shower\n```\n\nThis will schedule a shower tomorrow at 8pm with a notification at the time of the appointment. You can also use `saturn e`.\n\n### Formats\n\nThere are numerous formats that can be used for different times, dates, and durations. Localization is desired but I haven't found a good set of tools for doing it yet.\n\n#### Dates\n\nDates can be represented a number of ways:\n\n-   `today`, `tomorrow`, and `yesterday` are case-insensitive and have their traditional relative meanings.\n-   A day (integer) by itself will assume the current month and year.\n    -   You can also end the day number with traditional suffixes such as `th`, `st`, `nd`, etc.\n-   `month/day` (e.g. 8/7) will assume the current year.\n-   `year/month/day` (e.g. 2023/8/7) will represent a full date.\n-   The following day names and abbreviations can be used. The current day, e.g. if today is Friday, will mean today. Otherwise, it means the next day in the following week with that name. The words are not case-sensitive.\n    -   Sunday: \"Sun\"\n    -   Monday: \"Mon\"\n    -   Tuesday: \"Tu\", \"Tue\", \"Tues\"\n    -   Wednesday: \"Wed\", \"Weds\"\n    -   Thursday: \"Th\", \"Thu\", \"Thurs\"\n    -   Friday: \"Fr\", Fri\"\n    -   Saturday: \"Sat\"\n-   The following characters can be used as date separators: `/`, `-`, and `.`.\n\n#### Times\n\n-   `hour:minute:second` represents a full time. You may also use `.` for the separators.\n-   `hour:minute` 24-hour time with the following exception: for today's date: when less than 13 represents the time in relationship to the current 12-hour clock. 13 and above are 24-hour time. You can change this behavior with `saturn config set24h-time`.\n-   `hour:minute[pm|am]` represents the current 12 hour time with appropriate time of day designation.\n-   `hour[pm|am]` represents the top of the hour in 12 hour time with the appropriate time of day designation.\n-   `hour` represents the top of the hour in 12 hour time with the current time of day designation.\n-   `midnight` can be used to refer to `00:00` or `12:00am`\n-   `noon` can be used to refer to `12:00` or `12:00pm`.\n\n#### Durations\n\nAll duration rules take from the [fancy-duration](https://github.com/erikh/fancy-duration) crate.\n\nDurations are combined in order of precedence with single character designations for each unit. Example: `2h15m12s`, is \"2 hours, 15 minutes, and 12 seconds\".\n\n-   `s`: seconds\n-   `m`: minutes\n-   `h`: hours\n-   `d`: days\n-   `w`: weeks\n-   `m` (leading position only): months\n-   `y`: years\n\n## Querying\n\n**NOTE**: For Google Calendar, all listings that are unbounded time-wise have a current maximum bound of 30 days back, plus 30 days ahead. This is to ensure we grab all the results if possible in a single fetch, as well as not destroy your network each time you want to query this information for old or large calendars. `saturn` is not currently capable of backing up your Google Calendar.\n\n### Listing\n\n```\nsaturn list [--all]\n```\n\nWill list the database for today, or if `--all` is passed, will list the entire db. Note that `saturn today` and `saturn t`, and `saturn l` are synonyms for `saturn list`.\n\n```\nsaturn now [--well=\u003cduration\u003e]\n```\n\nWill list the items that need to be addressed immediately. To configure how much of a time to wrap around what \"now\" means, use the `--well` option. Durations are specified in [fancy-duration](https://github.com/erikh/fancy-duration) format.\n\n`saturn n` is an alias for `saturn now`.\n\n### Notifying\n\n```\nsaturn notify [--well=\u003cduration\u003e] [--timeout=\u003cduration\u003e]\n```\n\nWill display a notification to the screen for every item that must be addressed immediately. `--well` is similar to `now`'s functionality, and `--timeout` configures how long to keep the notification up on the screen.\n\nThis is what a notification looks like in `dunst`, which the notification system for `i3`. GNOME, KDE, MacOS, etc will look different, but have the same text.\n\n\u003cimg style=\"width:50%\" src=\"notification.png\" /\u003e\n\n### Editing\n\n```\nsaturn edit [-r] \u003cid\u003e\n```\n\nWill run `$EDITOR` and fill it with a YAML file. When this file is edited, it will change the database and the remote side, if necessary. Specify `-r` for recurring task IDs.\n\n### Deletion and Mutation\n\n```\nsaturn delete \u003cids...\u003e\n```\n\nWill delete a calendar record by ID, which is listed with the listing tools. Pass `-r` to delete a recurring task.\n\n```\nsaturn complete \u003cid\u003e\n```\n\nWill mark a task as \"completed\". Completed tasks get a visual notification and are automatically excluded from listing without the `--all` flag.\n\nDoes not work with Google Calendar.\n\n### Search\n\nSearch is only available on `main` branch, or v0.4.0+.\n\nSearch allows you to search by metadata using an English-like syntax similar to `saturn entry`. You can initiate this search by using `saturn search` or `saturn /` (a literal forward slash) followed by the metadata commands. In `sui`, you can use `search` or `/` at the prompt with the same syntax.\n\nIn `sui`, search does not live update; you must execute the search command again to see new results.\n\nTimes, Dates and Durations are all the same as mentioned earlier in this document. Search terms can be combined to form more advanced queries; currently, the only boolean operation is \"AND\", so for example two separate dates will result in no results as nothing can match both. Boolean operations in search are a planned feature.\n\nThe terms (and their parameters) follow:\n\n-   `field`: field takes a required `key` parameter which is followed by the name of the key you want to search for. If a value is omitted, only presence of the key is required. To provide a value, specify `value`. Keys and values do not need to be presented in any specific order.\n-   `date`: Specify a date to match. If the keyword `from` is provided in the first position instead of a date, you may specify a date range with the syntax `\u003cstart date\u003e to \u003cend date\u003e`.\n-   `time`: Specify a time to match. `from` works just like with `date`.\n-   `detail`: This is the summary of your event, and is a substring, case-insensitive match. Regular expressions and other free-form text options will come eventually.\n-   `recur`: This matches all tasks that belong to a specific recurring task, specified by ID. Use `show recur` in `sui` or `saturn list -r` to list recurring tasks.\n-   `finished`: For tasks that support being marked completed, this only matches those.\n-   `unfinished`: the inverse of `finished`.\n\nAs mentioned prior, search terms can be combined with boolean \"AND\", which is implicit. Here are some examples of search terms you can use:\n\n-   `saturn search date 10/23`: Find all calendar items that are on October 23rd of this year.\n-   `saturn search date 10/23 time from 2pm to 10pm`: Find all calendar items that are on October 23rd and occur between 2 and 10pm.\n-   `saturn search date 10/23 time from 2pm to 10pm detail Scarlett`: Find all calendar items that are on October 23rd and occur between 2 and 10pm and contain the word \"Scarlett\" in the item summary.\n-   `saturn search date 10/23 time from 2pm to 10pm detail Scarlett unfinished`: Find all calendar items that are on October 23rd, occur between 2 and 10pm, contain the word \"Scarlett\" in the item summary and have not been completed.\n\nTo return to the full listing in `sui`, use one of the `show` commands, such as `show all`.\n\nSearch will evolve over time and suggestions on how to improve it are welcome.\n\n## Database \u0026 Configuration File\n\nSaturn keeps a CBOR database in `~/.saturn.db`. Locking is flock(2), and quite primitive. Suggestions and patches welcome.\n\nThe configuration file is only required in limited scenarios (such as remote calendar support) and exists in `~/.saturn.conf`. It is a plain YAML file, but is typically manipulated by `saturn config` commands, which may replace any comments or other manipulations you previously did to the file by hand.\n\n## Leveraging the well features with a periodic scheduler\n\nThe `--well` options take a duration. This duration is intended to roughly match the frequency at which you run the program, so that there is little to no overlap between event firings. This flag is provided for `saturn now` and `saturn notify`.\n\nNotifications (specified by a `notify` entry stanza) are only fired once in any event. Events, on the other hand, are shown every time they fall into the window, which is the current time, +/- the `--well` duration.\n\nI hope this clears things up; I was trying to figure out a good way to run this in `cron` etc without spamming myself with notifications for a long period of time.\n\nHere's an example: we run a loop of `saturn notify` with a well of two minutes, and then we sleep for a minute. This allows notify to catch the alert only once, passing it up by the next time it runs.\n\n```bash\nwhile true\ndo\n    saturn notify --well 2m\n    sleep 60\ndone\n```\n\n## Recurring tasks\n\nRecurring tasks start their entry with the \"recur\" keyword and a duration. Every time the program is run and touches the database, it will look to add recurring tasks. Recurring tasks are based off the last task that was saved, and every recurrence up to the current point will be added in the absence of them. In the Unix file implementation, (not Google Calendar, which is responsible for creating its own recurring events) until they are added, they will not have IDs nor can they be manipulated. Commands like `now` and `notify` which only perform read operations also adjust this data, so they can fire notifications properly for new tasks.\n\n## Google Calendar Support\n\nGoogle Calendar support is working, with OAuth credentials being setup properly and limited control of the calendar is possible within the realm of what saturn currently supports. More is anticipated to be built atop this framework. Do not be surprised if functionality is confusing or missing. Please put in issues with your concerns, thanks!\n\n`sui` also works beautifully with Google Calendar, providing a compelling, if primitive replacement for the web UI.\n\nTo use `saturn` with Google Calendar, you must create a Google Cloud account and assign an OAuth application to it. One is not provided automatically by using `saturn` to eliminate concerns of data provenance.\n\nTo do this, follow [these steps](https://developers.google.com/calendar/api/quickstart/go), which go into how to set up an application for development. Be sure to setup any accounts you want to use as \"Test Users\", and ensure that `https://www.googleapis.com/auth/calendar` is in your list of allowed scopes.\n\nOnce you have the \"Client ID\" and \"Client Secret\", run this command:\n\n```bash\nsaturn config set-client \u003cclient id\u003e \u003cclient secret\u003e\nsaturn config get-token\nsaturn config db-type google\n```\n\nThe `get-token` command will have you access a URL in your browser and make you login to the google account you wish to use, which must be listed in your \"testing users\" in the OAuth setup above. As a final step, it will call back into a web service the application starts, which will feed it the token.\n\nYour token will expire if you do not use the tool regularly. Stuffing `saturn notify` in cron will alleviate this a bit. To get a new key, use `saturn config get-token` and follow the prompts. No other settings need to change.\n\nSetting the db-type will change the source of data. If you were using a local database and want to go back to it, `saturn config db-type unixfile`.\n\nNotifications setup in Google Calendar are not honored yet. This will be resolved soon!\n\nOther things we want to do that aren't here yet:\n\n-   Fields (URLs, Locations, etc)\n-   Attendees\n\n## TUI Commands\n\nThe TUI accepts several commands at the prompt; this command-set will grow with time. To interact with it, just type and hit enter to send a command.\n\n-   `e` or `entry`: Process an entry in `saturn entry` format.\n-   `d` or `delete`: Delete all the IDs provided (separate them with spaces). `d recur` or `delete recur` to delete recurring items.\n-   `show today` will show today's calendar items, where `show all` will show the entire calendar (the default).\n-   `show recur` will show you recurring tasks.\n-   `show \u003cid\u003e` will show you more information about that particular task. Use `show recur \u003cid\u003e` to show a recurring id.\n-   `edit \u003cid\u003e` will raise an editor to edit your item's properties. `edit recur \u003cid\u003e` will edit a recurring item.\n-   `quit` will exit the program.\n\n## Target Platform\n\nDue to flock(2) use, which to the best of my knowledge is the only reason, Windows probably does not work properly. Patches welcome if there are windows users who'd like to use it.\n\n## Author\n\nErik Hollensbe \u003cgit@hollensbe.org\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikh%2Fsaturn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferikh%2Fsaturn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikh%2Fsaturn/lists"}