zk: a plain text note-taking assistant for the command line

The problem zk solves, and who it is for

Most note applications own your notes. They store them in a database or a proprietary format, and the query layer only works inside that application. zk takes the opposite position. The README describes it as a command-line tool helping you maintain a plain text Zettelkasten or personal wiki, and the notes stay as Markdown files in a directory you control.

The audience is narrow and specific. You already write notes as files. You want to find them by tag, by link, by mention, or by date, from a shell or from inside an editor. You are comfortable with a config file in TOML and with the idea that a tool can be a query engine rather than an application. The README also lists what zk is not: it is not a note editor, and it is not a tool to serve your notes on the web. That boundary matters more than the feature list, because it tells you where the project stops.

The topics on the repository (cli, documentation-tool, notes, second-brain, wiki, zettelkasten) match that framing. If you want a wiki you browse in a browser, zk is the wrong layer.

How the index and the note format actually work

zk reads Markdown. The README says it supports most Markdown syntax flavors, and lists the pieces it parses: regular Markdown links and [[Wikilinks]], tags written as #hashtags, :colon:separated:tags: or Bear-style #multi-word tags#, and YAML frontmatter. Those parsed elements are what the search and filtering features operate on, which is why the README can advertise filtering by tags, links and mentions rather than just full-text matching.

The dependency list in go.mod shows the machinery. github.com/mattn/go-sqlite3 and github.com/yuin/goldmark are both present, so the pipeline is Markdown parsed by goldmark, with SQLite as the store behind the queries. The Makefile builds with -tags "fts5", which is the SQLite full-text search extension. That tag is not optional decoration: if you build zk yourself without it, you lose the full-text search path the release binaries are compiled with.

go.mod pins Go 1.25.0, while the README's build instructions say you need a working Go 1.21+ installation. Treat the module file as the accurate floor for building from source.

The rest of the surface is configuration. The README points to git-style command aliases and named filters, both defined in the config file, and to an interactive browser powered by fzf. Editor integration is not a plugin inside zk; zk exposes an LSP server (the tliron/glsp and sourcegraph/jsonrpc2 dependencies are in go.mod) and separate projects consume it. The README names zk-emacs, zk-nvim for Neovim 0.8+ and zk-vscode for Visual Studio Code.

Installing zk and creating your first notebook

The README points to the latest release page for pre-built binaries for macOS, Linux and Windows, with a warning worth reading: the binaries are not code-signed, and Windows Defender and other security tools have flagged some versions of the Windows binary as malicious in the past. The README states that building zk yourself is currently the recommended workaround on Windows.

On macOS, Homebrew is the shortest path.

brew install zk

That installs the released version. The README also documents brew install --HEAD zk if you want the latest state of main. Other packaged routes named in the README include apk add zk on Alpine (currently in the testing repositories), sudo pacman -S zk on Arch, and sudo port install zk on MacPorts. Nix users can run it without installing anything:

nix run nixpkgs#zk

To build from source, clone the repository and use the Makefile targets the project documents for its own builds.

git clone https://github.com/zk-org/zk.git
cd zk
make build

The README notes that the latest state of main can be considered the stable pre-release state, and that the dev branch is for the absolute latest state with bugs to be expected. Contributors are told to branch from dev, not main.

Once the binary is on your PATH, the first real step is creating a notebook. The README links a getting-started page under docs/tips rather than spelling the whole flow out inline, so the workflow below follows the project's own documentation structure: a notebook directory, then notes created from templates. The README documents note creation from templates and links a getting-started page for the exact commands.

After a notebook is initialized, the directory holds a .zk configuration folder alongside your Markdown. Notes created from templates appear as new Markdown files with frontmatter and a title, ready to edit in whatever editor you already use. zk itself will not open them for you; that is the point.

Where zk gets in your way

The most concrete limitation is the one the project states itself. zk is not an editor. Every time you create a note you get a file path and a shell prompt, and you need your editor wired up to open it. That is a real cost if you are used to pressing a key and typing.

The second is the Windows binary situation. The README's warning about code-signing and Defender flags is not a footnote you can skip if Windows is your platform. The documented workaround is to build from scratch, which means a Go toolchain and the fts5 build tag.

The third is the index. Because queries run against a SQLite index built from your files, anything that writes notes outside zk can leave the index stale until it is refreshed. The README does not document rollback or index recovery behaviour, so if you plan to sync a notebook across machines with a file-syncing service, verify how the index behaves before trusting it.

Finally, the build has a C dependency: CGO_ENABLED=1 appears in the Makefile's environment prefix, and the Alpine target adds -extldflags=-static because musl needs statically linked libraries. A pure-Go, single-static-binary story is not what this project offers.

zk against Neuron, Emanote and Weave

The README's related projects section is unusually honest about the split. Neuron is described as a tool to publish a Zettelkasten on the web, Emanote as an improved successor to Neuron, and Weave as another tool to publish Zettelkasten on the web. Those three answer a question zk explicitly refuses: how do I turn my notes into a site?

The difference in approach is architectural. Publishing tools read your Markdown and render HTML, usually with their own link syntax, their own templates and a build step that produces a static site. zk reads your Markdown and builds a queryable index, then answers questions from the shell or over LSP. One produces pages; the other produces answers. The README even links a static sites tip page as the sanctioned way to get zk-style notes onto the web, which is an admission that this is out of scope rather than a gap to be filled later.

There is a second comparison worth naming. sirupsen's zk is described in the README as a collection of scripts with a similar purpose. That is the honest alternative for someone who wants a shell script rather than a compiled tool with a config file and an index.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-12. Releases have been frequent through 2026: v0.15.4 on 2026-05-04, v0.15.5 on 2026-06-08 and v0.15.6 on 2026-07-26. The README points to CHANGELOG.md for the list of upcoming features waiting to be released, so the changelog is the file to read before upgrading rather than the release page alone.

Upgrade cost is low in the usual case, because your notes are files. A new zk version does not migrate a note format; it rebuilds an index. The place where versions can bite is the config file, which the README documents as TOML with aliases and named filters, and the Home Manager module, which manages ${XDG_CONFIG_HOME}/zk/config.toml through programs.zk.settings. If you use that module, your config lives in your Nix configuration and upgrades pass through it.

The licence is GPL-3.0, per the repository's LICENSE file. That is a copyleft licence. If you are only running the zk binary to query your own notes, the practical question is not the same as if you were linking zk's code into another program or shipping a modified binary. The repository does not offer a separate commercial licence in the documentation available, and this is not legal advice; check with whoever handles licensing where you work before embedding zk in a product.

Editorial conclusion

Adopt zk if your notes are already Markdown files on disk and you want search, filters and editor integration without a database in the middle. Do not adopt it if you want an editor, a web view of your notes, or a hosted service; the README states plainly that it is none of those. Before committing, run zk init in a scratch directory, check that the fts5 build tag is present in your install, and confirm how your editor plugin of choice talks to the LSP server.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. zk-org/zk on GitHub