stup - Daily notes in the terminal

Introducing a shell tool for saving, organizing and searching daily notes from the command line
Αυτό το άρθρο είναι διαθέσιμο και στα ελληνικά.

Over the past few years I have been participating in Stand-up meetings and it took me some time to find a convenient and effective way for keeping notes about what I was doing every day.

I needed to be able to:

  • keep notes on the issues I worked on, the meetings I participated in and stuff that blocked my work
  • easily access these notes based on their date
  • have an overview of what I did for example the last week
  • all of the above from inside a terminal without
    • having to manually structure and update a single document
    • having to manually create a document for each day


I created stup (the name derives from stand-up), an opensource CLI tool that deals with these issues and allows to easily save, access and organize my notes.

stup demo gif

The source code of the project is available on GitHub here.

Usage examples

Find below some examples showing the most important usage of stup.

Adding notes

# Adding a note to the default category at current date
stup add -n "Worked on issue #ABC123"

# Adding a note to the default category setting the current date explicitly
stup add today -n "Worked on issue #ABC123"

# Adding a note to the meetings category
stup add today -c "meetings" -n "2 hours with @phoebe for the project kick off"

# Adding a note to the blocking category for April 10th, 2020
stup add @ 2020-04-10 -c "blocking" -n "connectivity issues"

Showing notes

# Showing yesterday's notes
$ stup

# Showing yesterday's notes explicitly setting the date
$ stup yesterday

# Showing today's notes
$ stup today

# Showing notes on a specific date
$ stup show @ 2020-04-18

# Showing notes on a specific date for the meetings category
$ stup show @ 2020-04-18 -c "meetings"

Retrieving all notes for a period of time

# List current week's notes
stup log week

# List previous week's notes
stup log previous-week

# List notes between January 20th, 2020 and March 2nd, 2020
stup log --from 2020-01-20 --to 2020-03-02

# List meeting notes between January 20th, 2020 and March 2nd, 2020
stup log --from 2020-01-20 --to 2020-03-02 -c "meetings"

Behind the scenes

Notes are organized in categories.

When a new note is added, stup creates a markdown file and places it under the category’s directory in a sub-directory with a path based on the date.


# For example, the notes of a category named "programming" April 18th, 2020 are saved under

This allows users to retrieve any notes added on a specific date or in a specific period for a specific or for all categories.

# Fetch notes for all categories
$ stup show @ 2020-04-18

# Fetch notes for a specific category for previous week
$ stup log previous-week -c programming

# Fetch notes for all categories for a specific period
$ stup log --from 2020-04-01 --to 2020-04-15

More information

You can:

  • visit the project repository on Github here.
  • view the full documentation of stup here.
  • browse the project’s issues here.

That’s all, thanks for reading! Cat photo.

Phoebe, my cat, keeping notes without stup