My increasingly adequate website

Sync calcurse with a smartphone

calcurse is a text-user interface calendaring program. It's simple, fast, and its keyboard controls are efficient. If you can run it on a remote server that you have regular access to, it becomes the perfect "cloud" calendar (and since it lives on your hardware, you'll never have to worry about capitalist ad-mongers or the NSA).

Calcurse comes up a little short only if you want to use it from a smartphone. Connecting to your server using an SSH app and then working with calcurse via the onscreen keyboard is cumbersome. Imagine if that person you have a crush on asked you your plans for Saturday -- do you really want to delay your answer by having to log in to your server and fiddle with launching a program from the command line?

Fortunately, a little elbow grease can get calcurse and your phone working in harmony. You won't be able to create or edit appointments on your phone, but you will at least be able to view them.

In this page I outline three methods to get appointments from calcurse to sync with your phone. I will list them in the order of complexity and resources required.

Mailing yourself your calcurse appointments

The simplest way to get calcurse appointments to your phone is to make calcurse output a certain number of days' events and email them to you. This method requires that your system be able to send mail using the program called mail. I don't know anything about this, so either use a system where this works out of the box (OpenBSD, but not Debian) or figure out how to set it up.

Anyway, begin by deciding how many day's worth events you want to see. Here's the command to have calcurse print 14 days worth of appointments:

calcurse -r14

Step back for a second. Reflect that one of the key features of Unix is that it can take text that would normally be displayed on the screen and either save it to a file (we'll use this in the last two methods) or use it as input for another program (this is called piping).

Now let's take the output generated by the command above and pipe it to the mail program, telling mail to take that text and send it off to an email address:

calcurse -r14 | mail youremail@email.com

To make it easier to do this repeatedly, you can add the line a line like the following to the config file of whatever shell you use:

alias calmail="calcurse -r14 | mail youremail@email.com"

From now on you can type calmail to have 14 days worth of calendar appointments sent your phone.

If you want your calendar emailed to you, say, every evening, simply enlist the help of cron, a Unix utility that runs in the background and executes commands at given times. This obviously requires that your computer be on when cron is supposed to do something or it isn't done.

To use cron, open up its configuration file by typing crontab -e. This opens up /etc/crontab with your editor (always use crontab -e, though). Add a line like this:

00 17 * * * * /usr/local/bin/calcurse -r14 | /usr/bin/mail youremail@email.com

The numbers and asterisks before the command mean that the command will be executed on the 00th minute of the 17th hour, on every day of every week of every month. If you want to be emailed more than once a day, or less than once a day, consult this handy cron tutorial or refer to the cron manual page. Also note that cron wants me to use the full path to the program I am executing.

Outputting your calcurse appointments as a webpage

We can also tell calcurse to output our appointments to a file we can access from the Internet.

This method has two advantages over having our appointments mailed to us. First, we don't need to worry about our inbox filling up; we could tell calcurse to export our calendar every five minutes and we'll never see more than the latest file. Second, we're not reliant on email access. We can visit a simple URL to view our calendar -- a real boon when you're on a strange public computer where for reasons of sloth, security, or set-up your email is beyond your reach.

The downside, and this is a big one, is that this method requires access to a web server. If you're using calcurse on a remote server in the first place I don't think this is an unfair assumption. However, if you need to host the file on a machine other than the one running calcurse, investigate how to use something like sftp to transfer the outputted calcurse text file to the webserver.

As before, start by determining how many days worth of appointments you want to view. Let's try a month's worth of appointments and all our todo items. The command is this:

calcurse -r30 -t

Instead of sending the output to another program, as we did with mail, we redirect the output of calcurse to a text file in the directory where our webserver serves files from:

calcurse -r30 -t > /var/www/htdocs/cal.txt

Since your normal user probably doesn't have write access to /var/www/htdocs you may need to run this command as root. However, because calcurse defaults to using the .calcurse directory in the home directory of the user running it, calcurse ran as root works with /root/.calcurse. This isn't what you want since your calendar is worked on as user sarah (for example) and therefore stored in /home/sarah/.calcurse. You can tell calcurse to use a specific directory with the -D option:

calcurse -D /home/sarah/.calcurse -r30 -t > /var/www/htdocs/cal.txt

You will probably want cron to automate this process. This way you don't have to type things out, and you can have cron run that command every few minutes, ensuring you're always looking at the latest version of your calendar. In my case, I edit root's crontab to have this line:

*/5 * * * * /usr/local/bin/calcurse -D /home/sarah/.calcurse -r30 -t > /var/www/htdocs/cal.txt

Anyway, now I can load up https://www.increasinglyadequate.com/cal.txt and see my calendar as a text file. The formatting's not the greatest, but it works. Save this URL as a bookmark on your app screen and you've practically got your own calcurse mobile app -- albeit one that presents appointments and tasks in only one view.

Subscribing to calcurse as an ics/ical feed

Probably the best way to access calcurse through on a smartphone is to export your calcurse calendar as an ics file, put it on the Internet, and then subscribe to it using an app on your phone. (This will also work with web services like Google Calendars and desktop software like Outlook.)

The advantage to this method is that you get full integration with your phone's calendar, which means you get alarms, pop-ups, and even the ability to quickly search for appointments, among other benefits. Bear in mind, however, that however slick this is, it only works in one direction -- you can't make appointments on the phone and send them back to calcurse. For this reason it's more common to subscribe to calendars with holidays and other things you wouldn't change, but whatever.

This time, instead of simply outputting a few days worth of appointments as a text file, we tell calcurse to export its entirety as an ics file. The command format looks like so:

calcurse --export > calendar.ics

As before, we have to get this on the Internet.

I have cron export my calcurse appointments file in ics format and put it in the directory which Apache serves up as my website. I do this every five minutes, like so:

*/5 * * * * /usr/local/bin/calcurse -D /home/sarah/.calcurse/ --export > /var/www/htdocs/calcurse.ics

We now have an ics file accessible from the Internet. The next step is to configure our calendar program to subscribe to this feed. I'll show you how to do this in iOS 6.1.4, Google Calendar, and Outlook 2010.

Subscribing to an ics file in iOS:

1. Open the Settings application.
2. Choose to Mail, Contacts, Calendars.
3. Under Accounts, choose Add Account...
4. In the list of account types, choose Other.
5. Under Calendars, choose Add Subscribed Calendar.
6. Enter the URL of your calendar and tap next.
7. Enter a description and adjust other options if necessary, then tap save.

Subscribing to an ics file in Google Calendar:

NOTE: ics subscription in Google Calendar is sketchy. I have found forum posts from the last seven years complaining that Google Calendar won't bother with a subscribed ics file after its first read. I also have had this problem. Sometimes it works, sometimes it doesn't.

Also, Google Calendar has some issues with time zones and subscribed ics files. It assumes the times in my ics file are UTC and adjusts them back many hours. I had to tell Google Calendar that I live in Iceland (UTC+0 currently) to get around this.

For these reasons I suggest you consider a different calendar app if you're using an Android device. Ones that seem to allow you to sync with an ics file are Business Calendar. CalenGoo, and Fliq Calendar, among others, but I've never used any of these and can't vouch for them.

1. On the Google Calendar website (this cannot be done from the mobile app as far as I know), find your list of calendars on the left side of the screen.
2. Click the downward-pointing triangle context menu icon next to the text reading Other Calendars. In the drop-down menu select Add By URL.
3. Enter your ics file's URL and click add calendar.

Subscribing to an ics file in Outlook 2010

1. Open the Calendar view.
2. Click Open Calendar and select From Internet.
3. Enter the URL of your ics file and click OK.
4. At the next prompt, click yes.