friends is a volunteer project. If you find it valuable, please consider making a small donation (🙏) with the Sponsor button at the top of this page to show you appreciate its continued development.

friends

Spend time with the people you care about. Introvert-tested. Extrovert-approved.

NOTE: Participation is encouraged! Make issues, ask questions, submit pull requests (even if it's your first time contributing to open-source—you'll get lots of help), and give feedback! This project is very much alive!

Table of Contents

• Overview
• Installation
• A note on output
• Usage
  • Core concepts
  • Global flags
  • Syncing across multiple machines
  • Setting reminders
  • Command reference
    • add
      • add activity
        • Setting a default location
      • add note
      • add friend
      • add tag
      • add location
      • add nickname
      • add alias
    • clean
    • graph
    • help
    • list
      • list activities
      • list notes
      • list friends
      • list tags
      • list locations
      • Advanced searching
    • remove
      • remove tag
      • remove nickname
      • remove alias
    • rename
      • rename friend
      • rename location
    • set location
    • stats
    • suggest
    • update
• Other documentation
• Contributing (it's encouraged!)
• Code of Conduct
• License

---

Overview

friends is a command-line program that helps you to keep track of your relationships with the people you care about.

friends gives you:

• More organization around staying in touch with friends and family.
• A way to track the ebbs and flows of your relationships over time.
• Suggestions for who to call or hang out with when you have free time, whether it's fifteen minutes or an entire weekend.
• A low-cost way to record and remember big moments in your life.

Its philosophy emphasizes:

• Simplicity—it should be quick and easy to use.
• Transparency—all data is stored in a human-readable Markdown file. No proprietary formats here! And in addition to being open-source, friends is very much open to new ideas. Please contribute!
• Intelligence—specify dates with English phrases like "yesterday." Specify friends with their first names, even when you're friends with many Joannes. friends will figure it out.

Installation

$ gem install friends

Easy, huh?

A note on output

To make its output easier to view and work with, friends "pages" its output. This means that when it has a lot to print it will let you scroll up or down in your terminal to view all of it.

By default, friends tries to use the less -RFX command for paging, which should be available on most systems, and if that is not available falls back to simply printing the output. However, you can set a different pager by setting the FRIENDS_PAGER environment variable. If you have less version 530 or later we recommend using this instead:

FRIENDS_PAGER="less -RF"

Usage

Core concepts

friends is structured around several different types of things:

• Activities: The things you do. Each activity has a date associated with it. Activities may optionally contain any number of friends, locations, and tags.
• Friends: The people you do activities with. Each friend has a name and, optionally, one or several nicknames. (Examples: John, Grace Hopper)
• Locations: The places in which activities happen. (Examples: Paris, Martha's Vineyard)
• Tags: A way to categorize your activities with tags of your choosing. Tags may contain colons and hyphens inside them. (Examples: @exercise:running, @school, @science:indoors:agronomy-with-hydroponics)
• Notes: Any additional information you want to record about a friend or location. (Example: John and Jane got engaged.)

The friends.md Markdown file that stores all of your data contains:

• an alphabetical list of all locations:

### Locations:

- Atlantis
- Martha's Vineyard
- Paris

• an alphabetical list of all friends and their nicknames and locations:

### Friends:

- George Washington Carver
- Grace Hopper (a.k.a. The Admiral a.k.a. Amazing Grace) [Paris]
- Marie Curie [Atlantis]

• an ordered list of all activities:

### Activities:

- 2018-11-01: **Grace Hopper** and I went to _Martha's Vineyard_. George had to cancel at the last minute.
- 2018-01-04: Got lunch with **Grace Hopper** and **George Washington Carver**.
- 2017-12-31: Celebrated the new year in _Paris_ with **Marie Curie**.
- 2017-11-15: Talked to **George Washington Carver** on the phone for an hour.

• and an ordered list of all notes:

### Notes:

- 2018-06-15: **Grace Hopper** found out she's getting a big Naval Academy building named after her. @navy
- 2017-06-06: **Marie Curie** just got accepted into a PhD program in _Paris_. @school

See the example friends.md file for more information.

Global flags

friends supports several global flags that can be used on any command when specified before the name of the command, like: friends [flags] [command].

These flags are:

• --colorless: Disable output colorization and other effects.
• --debug: Debug error messages with a full backtrace.
• --filename: Set the location of the friends file to use (default: ~/friends.md).

$ friends --filename ./test/tmp/friends.md clean
File cleaned: "./test/tmp/friends.md"

• --quiet: Quiet output messages.

$ friends --quiet add activity Went rollerskating with George.
$ # No output!

In addition, these flags may be used without any command:

• --help: Show the help menu. This is equivalent to friends help. Help menus are available for all levels of commands:

$ friends --help

$ friends list --help

$ friends list activities --help

• --version: Show the friends program version.

Syncing across multiple machines

Wouldn't it be nice to be able to use friends across all of your devices? Hooray, you can! Just put the friends.md file in your Dropbox/Box Sync/Google Drive/whatever folder and use the --filename flag. You can even set up a Bash/Zsh/whatever alias to do this for you, like so:

alias friends="friends --filename '~/Dropbox/friends.md'"

Setting reminders

Though friends has no built-in reminder functionality, it's easy to use a system like cron (Mac or Linux) or Task Scheduler (Windows) to set various reminders.

For example, on a Mac, the following crontab configuration results in every day at 9:00 p.m. a Terminal tab opening, printing "Time to journal!" and then launching an add activity prompt through friends:

0 21 * * * osascript -e 'activate application "Terminal"' &> /dev/null && osascript -e 'tell application "Terminal" to do script "clear && echo Time to journal! && friends add activity"' &> /dev/null

Here's another example (also for Mac) of using friends to suggest some people to hang out with every Saturday morning:

0 10 * * 6 osascript -e 'activate application "Terminal"' &> /dev/null && osascript -e 'tell application "Terminal" to do script "clear && echo Consider hanging out with one of these friends today: && friends suggest"' &> /dev/null

(If you use other tools, please share and we'll add to these examples!)

Command reference*

*Note that the command-line output is colored, which this README cannot show.

add activity

$ friends add activity Got lunch with Grace and George.
Activity added: "2018-01-04: Got lunch with Grace Hopper and George Washington Carver."

friends will automatically figure out which "Grace" and "George" you're referring to, even if you're friends with lots of different Graces and Georges.

Nicknames will be used to match friends in activities, just like formal names:

$ friends add activity Invented debugging with The Admiral.
Activity added: "2017-01-06: Invented debugging with Grace Hopper."

You can also use the first initial of a last name instead of the whole thing. friends will figure out what to do with those pesky perio