Alas
Alas is a command line utility for managing a plan in a single Markdown file.
An example plan:
# My Plan
## Inbox
- [ ] #home - Fix the lamp
- [ ] Update Rust
## 2020-08-01, Saturday
- [ ] Develop photos
- [X] Pay bills
## 2020-07-31, Friday
- Met with Mike and Molly
- [X] #work - Review open pull requests
- [X] #work - Fix the flaky test
The plan file has days in present and future that serve as your plan, but also past days that serve as a log.
Alas can insert new empty days into your plan, remove empty days from past, schedule tasks and help you stay in touch with your contacts.
Warning
Alas updates your backup file. Using alas
can destroy your data due to
unintended use or a bug in Alas. Always keep a backup of your plan file.
Alas has a built in backup, but it’s best to use a separate backup solution as well.
A version control system, such as Git is a convenient option.
Getting Started
Plan Template
First, use your favorite text editor to create a plan file (e.g. plan.md
):
# My Plan
## Inbox
## 2022-05-12
Start adding new days and tasks. You can use this plan file even without
the alas
command utility.
Installing Alas
If you are using MacOS or a Linux based operating system, visit the Alas
releases page and download
the latest release for your operating system. Add the Alas executable path
to your PATH
and you can run alas
with your plan file.
You can also put the executable in the same directory as your plan file and use the relative path to run Alas:
./alas plan.md
Windows
At the moment, we don’t provide an executable for Windows. However, you can try compiling Alas on Windows and running it. To compile Alas, you need Janet and JPM. See the Janet installation instructions for more information.
Since Janet wasn’t tested on Windows, we expect some problems. You can
try running alas
from the same directory as you plan file, to avoid path
related issues.
Common Usage
Alas is usually executed with the same command every day. For example:
alas --insert-days 3 \
--remove-empty-days \
--skip-backup \
--schedule-tasks scheduled.md \
--schedule-contacts contacts \
plan.md
To avoid typing the long command, you can create an alias for your shell or a small script and run that instead.
Here’s an example script that runs Alas on a plan file, runs Tmux and opens the plan file in Vim:
#!/usr/bin/env bash
cd ~/wiki
alas --insert-days 3 \
--remove-empty-days \
--skip-backup \
--schedule-tasks scheduled.md \
--schedule-contacts contacts \
plan.md
tmux new-session -d 'vim plan.md'
tmux -2 attach-session -d
Commands
--skip-backup
Alas will create a backup of the plan file before running any other commands, by
default. To skip creating a backup, pass the --skip-backup
option.
--stats
alas --stats
command will print the number of days in your plan, the number
of completed tasks and the number of pending tasks:
$ alas --stats ~/todo.md
2 days
3 completed tasks
1 pending task
--insert-days
alas --insert-days 3
will insert 3 new days (starting from today) in your plan
file.
--remove-empty-days
alas --remove-empty-days
will remove past days that don’t have any events or
tasks from the plan.
--report
alas --report 7
will print all tasks for the last 7 days, excluding today.
--schedule-tasks
Alas allows keeping a list of scheduled tasks in a separate file. For example:
# My Scheduled Tasks
- Meeting with John (on 2022-05-12)
- Tina's birthday (every year on 10-11)
- Run 20 minutes (every Monday)
- Run 20 minutes (every Thursday)
- #work - Weekly meeting (every Tuesday)
- #work - Deploy new version (every weekday)
- #work - Generate monthly report (every month)
- #work - Generate quarterly report (every 3 months)
You can then run the following command to insert matching scheduled tasks into your plan:
alas --insert-days 3 --schedule-tasks scheduled.md plan.md
Alas supports the following schedule options:
- Specific day of the week -
every Monday
,every Tuesday
, etc. - On weekdays -
every weekday
- any day of the week except Saturday and Sunday. - First of the month -
every month
. - First of the quarter -
every 3 months
- January 1st, April 1st, July 1st, October 1st. - A specific day every year -
every year on 05-15
. - A specific date -
on 2025-05-15
.
Note: Alas will insert scheduled tasks only for days that are already
present in the plan. If a day doesn’t exist, --schedule-tasks
won’t insert
a day. This means that it’s best to use --schedule-tasks
in combination
with --insert-days
. Alas will make sure that --insert-days
is always
executed before --schedule-tasks
.
If you don’t use --insert-days
, you need to insert empty days manually or in
some other way before running --schedule-tasks
.
--schedule-contacts
Alas can help you keep in touch with your contacts - family, friends and other people you know. Alas tracks when you last heard from a person and schedules a new task to contact the person if you didn’t hear from them in a while. Alas can also schedule a reminder for a birthday.
Each contact is stored in a separate Markdown file. All contact files should be in a single directory, separate from other Markdown files. For example:
├── contacts
│ ├── john-doe.md
│ ├── marry-doe.md
│ ├── jack-black.md
│ ├── ...
├── diary.md
├── plan.md
└── scheduled.md
Each contact file has the same structure - the contact name, details and the log of communication.
# John Doe
- Birthday: 04-27
- Category: B
## 2022-02-15
Talked over the phone about stuff.
## 2022-01-28
Grabbed a beer and talked about stuff.
The first line is the title that holds the contact name.
Then, there’s a list of details. Each detail has the same structure:
- Detail name: Detail value
A contact can have as many details as you need. However, 2 details are special:
Birthday
and Category
.
If a contact has a Birthday
detail and the value matches today’s date, Alas
will schedule a reminder to congratulate the person’s birthday.
A contact Category
can have one of these 4 values: A, B, C and D. The
idea was taken from Derek Siver’s article where
categories are defined as:
- A list: Very important people. Contact every three weeks.
- B list: Important people. Contact every two months.
- C list: Most people. Contact every six months.
- D list: Demoted people. Contact once a year, to make sure you still have their correct info.
The command input requires a path to the directory that holds the contact files. For example:
alas --insert-days 3 --schedule-contacts contacts plan.md
This command might insert new contact tasks for today:
# My Plan
## Inbox
- [ ] #home - Fix the lamp
## 2020-08-01, Saturday
- [ ] Contact John Doe
- [ ] Congratulate birthday to Marry Doe
- [X] Pay bills
Note: Alas will insert contact tasks only for days that are already
present in the plan. If a day doesn’t exist, --schedule-contacts
won’t
insert a day. This means that it’s best to use --schedule-contacts
in
combination with --insert-days
. Alas will make sure that --insert-days
is always executed before --schedule-contacts
.
--version
alas --version
will output the version and exit. This command is available
only when no other commands are used.
Running multiple commands
Alas supports running multiple commands:
alas --insert-days 3 --remove-empty-days plan.md