Jesse Laprade

fa

A command-line agenda written in Fennel.

Screenshot

A screenshot of a user adding and removing agenda items in a terminal

Table of Contents

About this document

This document assumes you have basic command line skills in a Unix-like environment.

Disclaimer

This is a hobby project I built for myself to keep track of friends’ and family members’ birthdays, appointments, etc.

As mentioned in the AGPL3, I take no responsibility, and am not liable for anything that fa deletes.

Backup anything you don’t want deleted.

Conventions used in this document

Platforms

Below is a list of platforms that fa can run on:

Requirements

Downloading fa

Before using fa, you need to download fa. This section guides you through downloading the fa.lua script, the fa binary, the fa source code.

This section consists of the following sections:

Downloading the fa script

The fa script is a Lua file you can move around your system or place in a directory on you $PATH. This allows you to use fa from anywhere on your system.

To download the fa script
  1. Run curl https://git.m455.casa/fa/plain/dists/fa.lua -o fa && chmod u+x fa

Note: You can move the fa script anywhere on your system or move it into a directory on your $PATH, such as /usr/local/bin.

Downloading the fa binary

The fa binary is a file you can move around your system or place in a directory on your $PATH. This allows you to use fa from anywhere on your system.

To download the fa binary
  1. Run curl https://git.m455.casa/fa/plain/dists/fa-bin -o fa && chmod u+x fa

Note: You can move the fa binary anywhere on your system or move it into a directory on your $PATH, such as /usr/local/bin.

Downloading the fa source code

The fa source code can be downloaded for people who want to compile from source. This method also makes installation easier, if you want to run fa from anywhere on your system.

To download the fa source code
  1. git clone https://git.m455.casa/fa

Compiling from source

This section guides you through using the Makefile to compile the fa source code into a Lua script called fa.lua or a binary called fa.

Before continuing, ensure you have all of the requirements.

This section consists of the following sections:

Compiling fa into a Lua script

This method creates a dists/fa.lua script.

To compile fa into a Lua script
  1. make compile-lua

Compiling fa into a binary

This method creates a dists/fa binary.

To compile fa into a binary
  1. make compile-bin

Installing fa

You can install the fa script or the fa binary included in the dists directory in this repository.

This section consists of the following sections:

Note: This section assumes you have downloaded the fa source code.

Installing the fa script

You can install the fa script using the make command. This allows you to run fa from anywhere on your system.

To install the fa script
  1. sudo make install-lua

Installing the fa binary

You can install the fa binary using the make command. This allows you to run fa from anywhere on your system.

To install the fa binary
  1. sudo make install-bin

Using fa

This section teaches you how to use fa’s commands.

This section assumes you have installed fa.

Initializing fa

Before using fa, you need to initialize it. When fa initializes, fa creates a ~/.fa file.

To initialize fa
  1. Run fa init

Showing the help message

The help message provides a list of available commands. This is list useful in case you forget the name of a command or how to use a command.

To show the help message
  1. Run fa help

Displaying your agenda

Displaying your agenda allows you to view the dates you have added to your agenda.

Note: These dates are useful references for when you want to remove dates from your agenda. For more information, see the Removing a date from your agenda topic.

To display your agenda
  1. Run fa ls

Displaying events from a specific date

fa allows you to only list events from a specific date. This removes the need to parse long agendas.

To display events on a specific date
  1. Run fa ls mmdd

Where mm is two numbers representing a month and dd is two numbers representing a day.

Example: fa ls 0112.

Adding a date to your agenda

Adding a date to your agenda saves it to a text file to access later.

To add a date to your agenda
  1. Run fa add mmdd "Your event text here"

Where mm is two numbers representing a month and dd is two numbers representing a day.

Example: fa add 0112 "Some event on January the 12th".

To add the current date to your agenda
  1. Run fa add today "Your event text here"

Removing a date from your agenda

When removing a date from your agenda, you can reference the date numbers beside each agenda item when displaying your agenda. You can use these numbers when removing a date from your agenda.

To remove a date from your agenda
  1. Run fa rm mmdd

Where mm is two numbers representing a month and dd is two numbers representing a day.

Example: fa rm 0112.

To remove the current date from your agenda
  1. Run fa rm today

Note: You may need to run fa ls first to see which numbers correspond with which date in your agenda.

Removing an event from your agenda

Each date contains a list of events. These events can be removed individually. This removes the need to recreate a date with multiple events when you only need remove one event.

To remove an event from your agenda
  1. Run fa rm mmdd n

Where mm is two numbers representing a month, dd is two numbers representing a day, and n is a number that correlates to an event.

Example: fa rm 1231 3.

Note: You may need to run fa ls first to see which numbers correspond with which event in your agenda.

To remove an event on the current date from your agenda
  1. Run fa rm today n

Where n is a number that correlates to an event.

Note: You may need to run fa ls first to see which numbers correspond with which event in your agenda.

Example: fa rm today 3.

List of commands

This section lists and describes fa’s commands.

Usage examples

Adding fa notifications to your tools

The fa notify command was intended to be placed in status bars or shell prompts.

The fa notify command outputs a ! without a trailing newline character (\n).

Adding notifications to your Bash prompt

This section provides an example of how you could add the fa notify command in a Bash prompt to check if the current date matches any of the dates in your agenda.

Note: This section assumes you have a fa executable in a directory on your $PATH.

To add notifications to your Bash prompt

  1. Add the following contents to your ~/.bashrc:

    event () {
  fa notify | awk '{ print " " $1 }'
}

yellow="\[\e[1;33m\]"
reset="\[\e[0;39m\]"

export PS1="\w$yellow\$(event)$reset > "

  2. Open a new terminal.

Here’s what it looks like:

A screenshot of a bash prompt with an exclamation mark to signify that an event is happening on the current date