nkt

[!IMPORTANT] The nkt source has moved to sr.ht

<p align="center"> <img width="80%" alt="Example screenshot of nkt in the terminal." src="assets/example.jpg"> </p>

A(nother) note taking solution for terminal enthusiasts.

nkt is a command line tool for helping you track and build your notes, todo lists, habits, and more. nkt mixes a number of different note-taking idioms, with inspiration from applications like Dendron, jrnl, vim-wiki and methods such as the incremental note-taking method, "Dont break the chain" and Zettelkasten.

Features:

• Bring your own $EDITOR
• Bring your own reader / renderer
• Bring your own document format (Markdown, LaTeX, typst, RST, ...)
• Everything stored as plain text and JSON, so easy to migrate if you end up hating it
• Support for journals, tasklists, notes, chains, and more...
• Tag things to help search your notes
• Fuzzy find anything and everything. nkt solves the problem of linking notes together to make navigation easy by letting you fuzzy find everything interactively similar to fzf.

Quick start <a id="toc-tag-mdtoc" name="quick-start"></a>

Download the binary for your architecture from the latest release. Put the binary in your $PATH and then initialize the home directory (~/.nkt):

nkt init

# log to a journal
nkt log "this is my first diary entry"

# create a new note
nkt edit books.reading-list --new

# edit an existing note
nkt edit films.watch-list

# search all notes with a fuzzy finder
nkt find

# add an item to your todo list
nkt task "learn more about that thing" --due monday

# list your tasks
nkt ls todo

# list your notes in the `notes` directory
nkt ls notes

# create a tag
nkt new tag work
nkt log "i am currently at @work"

# search journal entries matching a tag
nkt read --all @work

# list your tags
nkt ls tags

<!--BEGIN TOC-->

Table of Contents

1. Quick start
2. Description
3. Usage
   1. Shell completion
4. Concepts and details
   1. Tags
   2. Text compilers
5. Configuration
6. Reference
7. Installation
   1. From source
8. Known issues
9. Disclaimer

<!--END TOC-->

Description <a id="toc-tag-mdtoc" name="description"></a>

The design of nkt is centered around making it easy to get information into your notes, and making it easy to get information back out again. Principally, nkt provides four different ways to record information:

• Journal

  A journal is a collection of days, each of which is a collection of entries. The journal is the standard way to quickly jot something down you might want to remember; the command is designed to be short and sweet and to get out of the way quickly so you can continue on with what you were doing.

  Every entry in the journal is timestamped, and can be tagged using in-place tags or using post-fix tags. See Tags.

• Notes

  Notes are (longer form) textual notes that are kept in directories. Notes have dot-hierarchical names, so you don't have a directory called music and another one called composers into which you put Bach.md, but rather you have music.composers.Bach.md.

  Each note can be compiled with a text compiler into a rendered note for easy reading and navigation. See Text compilers.

• Tasks

  A task is kept in a tasklist, and represents a todo-item. Tasks can be given due dates (see Semantic time), have importance assigned to them, be tagged in various ways, and even have notes and descriptions attached to them.

• Chains

  Chains are for building habits. A chain is given a task or habit you are trying to build and then it can be checked off each day you complete that tasks.

• Stacks

  Stacks are for keeping track of how you got to the current state of something. They are stacks of notes that maintain a FIFO ordering. The use case they were supposed to address was for keeping track of reference trails when reading a paper.

Usage <a id="toc-tag-mdtoc" name="usage"></a>

To setup nkt, use the init command.

$ nkt help init
Extended help for 'init':

(Re)Initialize the home directory structure.

You can override where the home directory is with the `NKT_ROOT_DIR`
environment variable. Be sure to export it in your shell rc or profile file to
make the change permanent.

Initializing will create a number of defaults: a directory "notes", a journal
"diary", a tasklist "todo".

These can be changed later if desired. You must always have some defaults
defined so that nkt knows where to put things if you don't tell it otherwise.


Arguments:

    [--reinit]                Only create missing files and write missing
                                configuration options.
    [--reinit-all]            Opens and rewrite the ENTIRE nkt topology system. Useful
                                for reformatting JSON or applying modifications. Not for
                                general use.
    [--force]                 Force initializtion. Danger: this will overwrite *all*
                                topology files.

And that's it! You're all setup.

Shell completion <a id="toc-tag-mdtoc" name="shell-completion"></a>

nkt brings shell completion so you can use Tab to complete command line arguments, note names, even select specific entries from journals.

There is shell completion for the following shells:

• zsh:

  Generate the completions file

  nkt completion > _nkt
  

  Then move the _nkt file into your zsh completion path (e.g. ~/.zsh_completions/).

• Sorry, I only really use zsh at the moment and writing completion files is not a hobby of mine.

Concepts and details <a id="toc-tag-mdtoc" name="concepts-and-details"></a>

Before we look at how to put information in to nkt, let's quickly talk about a few ways of getting information out of nkt. For any successful note taking application, it's important to know how to find things again.

Most nkt commands that interact with something in your knowledge base use a selector to do so. The selector can be a pretty general statement, and has some semantic additions built in; for example:

• A number, like 1, 4, 7 means "n days ago". 1 will select yesterday. 0 is today.
• A date 2024-01-07 (in YYYY-MM-DD) will also select a specific day.
• A qualified number like t1 or t8 will select a specific task (we'll get onto those later).
• A name art.pre-raphaelite or maths will select an item by name. This could be the name of a note or the title of a task.

You can test what a selection will do using the select command. All of these can be made more granular by including, say, a --journal work flag to indicate you want to select 2 days ago in the work journal.

To select a specific entry, you need to choose both a day and pass a --time HH:MM:SS flag. This is where shell completion comes in handy, as you can do nkt select 0 --time <TAB> and a list of times will come up to select from.

Often, though, you don't know where something is stored, you just know it's somewhere. That's where find comes in useful as a fuzzy text finder. It's worth just having a look at help find to see what you can do with it, and also to know that it's aliased to f so you can just do nkt f when you're in a rush.

The other commands you will likely end up using the most are log, read, and edit. So let's introduce the stars of the show:

• log is used to add a new entry to a journal. It's there so when you need to quickly jot down an idea or a thought it's there for you. Log stores a timestamp for every entry so you can flick back through them easily.

• read is used to read different things. Without any arguments read will just print the last n entries from you journal, interweaved with any status changes in your tasklists. You can also use it to read specific notes, which will just get printed directly to your terminal.

• edit is used to add new notes into a directory or to modify existing information. edit will only create a new note if you tell it to, to avoid accidentally adding notes you didn't mean to.

  You can also use edit to modify an entry by selecting it by its timestamp on a certain day.

  If given no arguments, edit will go interactive (like find) and let you fuzzy search through the names of your notes. See help edit for more details.

This is probably enough to get going. Have a look at Tags to learn more about organising your notes effectively, and Text compilers to learn how to produce rendered versions of your notes.

Tags <a id="toc-tag-mdtoc" name="tags"></a>

Tags are used to group notes together to make finding what you know about a certain thing a little more structured. Tags are always prefixed with an @ symbol, such as @tag. To avoid spuriously introducing new tags, nkt forces you to define a set of tags that you are going to use. You can do this with the new command.

nkt new tag project.sewing

will create a new hierarchical tag project.sewing. This means that the tag is matched if you search for @project or @project.sewing. Similar to the hierarchical naming convention of the notes themselves, the naming is to help you subgroup and make clusters of information increasingly granular.

You can tag pretty much anything. To tag a selected item use

nkt tag --journal work 2 @meeting.town-hall

This will tag the day before yesterday in the work journal with `@m