{"id":21125201,"url":"https://github.com/fjebaker/nkt","last_synced_at":"2025-07-08T22:31:05.996Z","repository":{"id":262452934,"uuid":"713659119","full_name":"fjebaker/nkt","owner":"fjebaker","description":"Terminal note taking.","archived":false,"fork":false,"pushed_at":"2024-11-12T14:03:35.000Z","size":1401,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-12T14:31:47.671Z","etag":null,"topics":["cli","journal","note-taking","notes","productivity","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fjebaker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-03T01:14:43.000Z","updated_at":"2024-11-12T14:03:38.000Z","dependencies_parsed_at":"2024-11-12T14:45:33.261Z","dependency_job_id":null,"html_url":"https://github.com/fjebaker/nkt","commit_stats":null,"previous_names":["fjebaker/nkt"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjebaker%2Fnkt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjebaker%2Fnkt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjebaker%2Fnkt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjebaker%2Fnkt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fjebaker","download_url":"https://codeload.github.com/fjebaker/nkt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225466982,"owners_count":17478864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","journal","note-taking","notes","productivity","terminal","tui"],"created_at":"2024-11-20T04:22:03.977Z","updated_at":"2025-07-08T22:31:05.989Z","avatar_url":"https://github.com/fjebaker.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nkt\n\n\u003e [!IMPORTANT]\n\u003e The `nkt` source has moved to [sr.ht](https://sr.ht/~fjebaker/nkt/)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"80%\" alt=\"Example screenshot of nkt in the terminal.\" src=\"assets/example.jpg\"\u003e\n\u003c/p\u003e\n\n_A(nother) note taking solution for terminal enthusiasts._\n\nnkt is a command line tool for helping you track and build your notes, todo\nlists, habits, and more. nkt mixes a number of different note-taking idioms,\nwith inspiration from applications like [Dendron](https://www.dendron.so/),\n[jrnl](https://github.com/jrnl-org/jrnl),\n[vim-wiki](https://github.com/vimwiki/vimwiki) and methods such as the\nincremental note-taking method, \"Dont break the chain\" and\n[Zettelkasten](https://en.wikipedia.org/wiki/Zettelkasten).\n\nFeatures:\n- Bring your own `$EDITOR`\n- Bring your own reader / renderer\n- Bring your own document format (Markdown, LaTeX, typst, RST, ...)\n- _Everything_ stored as plain text and JSON, so easy to migrate if you end up hating it\n- Support for journals, tasklists, notes, chains, and more...\n- Tag things to help search your notes\n- 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](https://github.com/junegunn/fzf).\n\n## Quick start \u003ca id=\"toc-tag-mdtoc\" name=\"quick-start\"\u003e\u003c/a\u003e\n\nDownload the binary for your architecture from [the latest\nrelease](https://github.com/fjebaker/nkt/releases/latest). Put the binary in\nyour `$PATH` and then initialize the home directory (`~/.nkt`):\n```bash\nnkt init\n\n# log to a journal\nnkt log \"this is my first diary entry\"\n\n# create a new note\nnkt edit books.reading-list --new\n\n# edit an existing note\nnkt edit films.watch-list\n\n# search all notes with a fuzzy finder\nnkt find\n\n# add an item to your todo list\nnkt task \"learn more about that thing\" --due monday\n\n# list your tasks\nnkt ls todo\n\n# list your notes in the `notes` directory\nnkt ls notes\n\n# create a tag\nnkt new tag work\nnkt log \"i am currently at @work\"\n\n# search journal entries matching a tag\nnkt read --all @work\n\n# list your tags\nnkt ls tags\n```\n\n\u003c!--BEGIN TOC--\u003e\n## Table of Contents\n1. [Quick start](#quick-start)\n2. [Description](#description)\n3. [Usage](#usage)\n    1. [Shell completion](#shell-completion)\n4. [Concepts and details](#concepts-and-details)\n    1. [Tags](#tags)\n    2. [Text compilers](#text-compilers)\n5. [Configuration](#configuration)\n6. [Reference](#reference)\n7. [Installation](#installation)\n    1. [From source](#from-source)\n8. [Known issues](#known-issues)\n9. [Disclaimer](#disclaimer)\n\n\u003c!--END TOC--\u003e\n\n## Description \u003ca id=\"toc-tag-mdtoc\" name=\"description\"\u003e\u003c/a\u003e\n\nThe design of nkt is centered around making it easy to get information into\nyour notes, and making it easy to get information _back out again_.\nPrincipally, nkt provides four different ways to record information:\n\n- Journal\n\n  A journal is a collection of _days_, each of which is a collection of\n  _entries_. The journal is the standard way to quickly jot something down you\n  might want to remember; the command is designed to be short and sweet and to\n  get out of the way quickly so you can continue on with what you were doing.\n\n  Every entry in the journal is timestamped, and can be tagged using in-place tags\n  or using post-fix tags. See [Tags](#Tags).\n\n- Notes\n\n  Notes are (longer form) textual notes that are kept in _directories_. Notes\n  have dot-hierarchical names, so you don't have a directory called `music` and\n  another one called `composers` into which you put `Bach.md`, but rather you\n  have `music.composers.Bach.md`.\n\n  Each note can be compiled with a text compiler into a rendered note for easy\n  reading and navigation. See [Text compilers](#Text-compilers).\n\n- Tasks\n\n  A task is kept in a _tasklist_, and represents a todo-item. Tasks can be\n  given due dates (see [Semantic time](#Semantic-time)), have importance assigned\n  to them, be tagged in various ways, and even have notes and descriptions\n  attached to them.\n\n- Chains\n\n  Chains are for building habits. A chain is given a task or habit you are\n  trying to build and then it can be checked off each day you complete that tasks.\n\n- Stacks\n\n  Stacks are for keeping track of how you got to the current state of\n  something. They are stacks of notes that maintain a FIFO ordering. The use\n  case they were supposed to address was for keeping track of reference trails\n  when reading a paper.\n\n## Usage \u003ca id=\"toc-tag-mdtoc\" name=\"usage\"\u003e\u003c/a\u003e\n\nTo setup `nkt`, use the `init` command.\n```\n$ nkt help init\nExtended help for 'init':\n\n(Re)Initialize the home directory structure.\n\nYou can override where the home directory is with the `NKT_ROOT_DIR`\nenvironment variable. Be sure to export it in your shell rc or profile file to\nmake the change permanent.\n\nInitializing will create a number of defaults: a directory \"notes\", a journal\n\"diary\", a tasklist \"todo\".\n\nThese can be changed later if desired. You must always have some defaults\ndefined so that nkt knows where to put things if you don't tell it otherwise.\n\n\nArguments:\n\n    [--reinit]                Only create missing files and write missing\n                                configuration options.\n    [--reinit-all]            Opens and rewrite the ENTIRE nkt topology system. Useful\n                                for reformatting JSON or applying modifications. Not for\n                                general use.\n    [--force]                 Force initializtion. Danger: this will overwrite *all*\n                                topology files.\n```\n\nAnd that's it! You're all setup.\n\n### Shell completion \u003ca id=\"toc-tag-mdtoc\" name=\"shell-completion\"\u003e\u003c/a\u003e\n\nnkt brings shell completion so you can use Tab to complete command line\narguments, note names, even select specific entries from journals.\n\nThere is shell completion for the following shells:\n\n- zsh:\n\n  Generate the completions file\n  ```\n  nkt completion \u003e _nkt\n  ```\n  Then move the `_nkt` file into your zsh completion path (e.g. `~/.zsh_completions/`).\n\n- Sorry, I only really use `zsh` at the moment and writing completion files is not a hobby of mine.\n\n## Concepts and details \u003ca id=\"toc-tag-mdtoc\" name=\"concepts-and-details\"\u003e\u003c/a\u003e\n\nBefore we look at how to put information _in_ to nkt, let's quickly talk about\na few ways of getting information _out_ of nkt. For any successful note taking\napplication, it's important to know how to find things again.\n\nMost nkt commands that interact with something in your knowledge base use a\nselector to do so. The selector can be a pretty general statement, and has some\nsemantic additions built in; for example:\n\n- A number, like `1`, `4`, `7` means \"n days ago\". `1` will select yesterday. `0` is today.\n- A date `2024-01-07` (in `YYYY-MM-DD`) will also select a specific day.\n- A qualified number like `t1` or `t8` will select a specific task (we'll get\n  onto those later).\n- A name `art.pre-raphaelite` or `maths` will select an item by name. This\n  could be the name of a note or the title of a task.\n\nYou can test what a selection will do using the `select` command. All of these\ncan be made more granular by including, say, a `--journal work` flag to\nindicate you want to select `2` days ago in the `work` journal.\n\nTo select a specific entry, you need to choose both a day and pass a `--time\nHH:MM:SS` flag. This is where shell completion comes in handy, as you can do\n`nkt select 0 --time \u003cTAB\u003e` and a list of times will come up to select from.\n\nOften, though, you don't know where something is stored, you just know it's\nsomewhere. That's where `find` comes in useful as a fuzzy text finder. It's\nworth just having a look at `help find` to see what you can do with it, and\nalso to know that it's aliased to `f` so you can just do `nkt f` when you're in\na rush.\n\nThe other commands you will likely end up using the most are `log`, `read`, and\n`edit`. So let's introduce the stars of the show:\n\n- `log` is used to add a new entry to a journal. It's there so when you need to\n  quickly jot down an idea or a thought it's there for you. Log stores a\n  timestamp for every entry so you can flick back through them easily.\n\n- `read` is used to read different things. Without any arguments read will just\n  print the last `n` entries from you journal, interweaved with any status\n  changes in your tasklists. You can also use it to read specific notes, which\n  will just get printed directly to your terminal.\n\n- `edit` is used to add new notes into a directory or to modify existing\n  information. `edit` will only create a new note if you tell it to, to avoid\n  accidentally adding notes you didn't mean to.\n\n  You can also use edit to modify an entry by selecting it by its timestamp on\n  a certain day.\n\n  If given no arguments, `edit` will go interactive (like `find`) and let you\n  fuzzy search through the names of your notes. See `help edit` for more details.\n\nThis is probably enough to get going. Have a look at [Tags](#tags) to learn\nmore about organising your notes effectively, and [Text\ncompilers](#Text-compilers) to learn how to produce rendered versions of your\nnotes.\n\n### Tags \u003ca id=\"toc-tag-mdtoc\" name=\"tags\"\u003e\u003c/a\u003e\n\nTags are used to group notes together to make finding what you know about a\ncertain thing a little more structured. Tags are always prefixed with an `@`\nsymbol, such as `@tag`. To avoid spuriously introducing new tags, nkt forces\nyou to define a set of tags that you are going to use. You can do this with the\n`new` command.\n\n```\nnkt new tag project.sewing\n```\n\nwill create a new _hierarchical tag_ `project.sewing`. This means that the tag\nis matched if you search for `@project` or `@project.sewing`. Similar to the\nhierarchical naming convention of the notes themselves, the naming is to help\nyou subgroup and make clusters of information increasingly granular.\n\nYou can tag pretty much _anything_. To tag a selected item use\n\n```\nnkt tag --journal work 2 @meeting.town-hall\n```\n\nThis will tag the day before yesterday in the work journal with\n`@meeting.town-hall`.\n\nWhen writing entries or tasks, you can also use inline tag syntax\n\n```\nnkt log \"wrote an @email back to dorothy\"\nnkt task \"learn more @vim shortcuts\" --due tuesday\n```\n\nThese are automatically parsed and the entry / task is tagged with the\ncorresponding tag. The intended use is to make **tags semantically\nmeaningful**, so they can be embedded into sentences as you type the note.\n\nThe `log` command also supports out-of-place tagging\n\n```\nnkt log \"arrived at the office\" @work\n```\n\nThese tags will not appear in the body of the entry but are the equivalent of having used\n\n```\nnkt log \"arrived at the office\"\nnkt tag 0 --last @work\n```\n\nYou can use tags to guide your searches, or list everything tagged with a\ncertain tag using the `list` command\n```\nnkt ls @work\n```\n\n### Text compilers \u003ca id=\"toc-tag-mdtoc\" name=\"text-compilers\"\u003e\u003c/a\u003e\n\nText compilers are used to render a note. You can use pretty much any program\nunder the sun to do this, but for example you might want to use `typst` or\n`pandoc` for specific note types.\n\nYou can compile a note with\n```\nnkt compile --directory recipes dip.hummus --open\n```\n\nThis will use a text compiler to render a PDF of your note. The `--open` flag\nwill then open the compiled note in your configured `pdf` viewer.\n\nSee `help compile` for more information.\n\nnkt comes with some default text compilers. You can list those available as\nwell as the note extensions they support with\n```\n$ nkt (main) $ nkt ls compilers\n\nCompiler:         markdown\n - Extensions:    md\n\nCompiler:         typst\n - Extensions:    typ\n```\n\nLet's add a new one that will print the note out of an Epson thermal printer,\nso e.g. we can export our recipes quickly. We have to edit\n`~/.nkt/topology.json` to do this, and under the `text_compilers` heading add\n```json\n{\n    \"name\": \"epson\",\n    \"command\": [\n        \"/home/lilith/Developer/printing/print.py\",\n        \"--print\",\n        \"%\u003c\"\n    ],\n    \"link\": \"%NAME\",\n    \"extensions\": [\n        \"md\",\n        \"txt\"\n    ]\n}\n```\nWe give the name of the text compiler, the shell command used to execute the compiler (using `%\u003c` and `%@` to denote the input and output file respective, similar to Make), and specify any other flags we might want to add.\n\nNext the `link` entry tells nkt how to translate links. See the `markdown` and `typst` entries for examples. These are used to build links between one compiled note and another.\n\nFinally we give a list of extensions that this text compiler is valid for. We can use it by specifying the compiler, or it will be default selected if no other compilers for a given extension are available\n\n```\nnkt compile --directory recipes dip.hummus --compiler epson\n```\n\n## Configuration \u003ca id=\"toc-tag-mdtoc\" name=\"configuration\"\u003e\u003c/a\u003e\n\nMost things are pretty self evident regarding what they do. Check the\n`~/.nkt/topology.json` to see the configuration, and edit this file as you\nplease.\n\n## Reference \u003ca id=\"toc-tag-mdtoc\" name=\"reference\"\u003e\u003c/a\u003e\n\nPlease use\n```\nnkt help [subcommand]\n```\nfor up-to-date reference and documentation for each command.\n\n## Installation \u003ca id=\"toc-tag-mdtoc\" name=\"installation\"\u003e\u003c/a\u003e\n\nGrab one of the binaries from the [release]() for your architecture:\n\n- Linux Aarch64 (musl)\n- Linux x86_64 (musl)\n- MacOS M1\n- MacOS Intel\n- I don't know how to Windows\n\n### From source \u003ca id=\"toc-tag-mdtoc\" name=\"from-source\"\u003e\u003c/a\u003e\n\nClone this GitHub repository, and have [Zig](https://ziglang.org) installed.\nnkt is build using Zig version 0.14.0.\n\n```bash\ngit clone https://github.com/fjebaker/nkt \\\n    \u0026\u0026 cd nkt \\\n    \u0026\u0026 zig build -Doptimize=ReleaseSafe\n```\n\n## Known issues \u003ca id=\"toc-tag-mdtoc\" name=\"known-issues\"\u003e\u003c/a\u003e\n\n- Datetimes are ruining my life.\n\n## Disclaimer \u003ca id=\"toc-tag-mdtoc\" name=\"disclaimer\"\u003e\u003c/a\u003e\n\nI am writing nkt to fit my note taking and productivity needs. If it works for you, that's awesome, and we should be friends. If it doesn't, we should still be friends. But since the primary audience of nkt is _me_, please don't get too annoyed at me for rejecting feature requests, and feel free to fork the code and tailor the application towards your needs.\n\nIf nkt deletes all your notes for whatever reason, I am sorry, hopefully you did the `git` integration so have backups of them all, but also, this software has no warranties and I claim no responsibility for the information you put into your notes or access via nkt.\n\n---\n\nDependencies:\n- [frmdstryr/zig-datetime](https://github.com/frmdstryr/zig-datetime)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffjebaker%2Fnkt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffjebaker%2Fnkt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffjebaker%2Fnkt/lists"}