Diary CLI

diary records project learnings, bugs, features, decisions, ideas, and progress in a project-local LOG.md file. It is a small, local-first CLI for keeping a searchable project history in Markdown.

Install locally

This project requires Bun.

bun install
bun run link

The link script registers the diary executable with Bun. After that, use diary from any local project directory.

Diary keeps each project's source log in that project's own LOG.md. It also maintains a central notes directory containing one symlink to each project log. This gives you one folder—such as an Obsidian notes folder—from which you can browse all project diaries. The symlinks do not copy or move the logs.

The default central directory is ~/.diary/notes. To use another directory, edit defaultConfig.notesDir in ~/.diary/config.json after the first run:

{
  "defaultConfig": {
    "tags": ["bug", "feature", "learning", "done"],
    "stages": ["core-toy", "protocol"],
    "notesDir": "/home/me/notes"
  },
  "projects": {}
}

notesDir must be an absolute path. After initializing a project, the central directory will contain entries like my-project.LOG.md pointing to ~/projects/my-project/LOG.md.

Commands

Initialize the current project:

cd ~/projects/my-project
diary init

Initialization creates LOG.md, stores project-specific tags and stages, and creates <notesDir>/my-project.LOG.md as a symlink to the project log. This is what makes all initialized project logs visible in one central folder. Re-running it is safe and does not replace an existing log or conflicting file.

Add an entry:

diary
# equivalent
diary add

The interactive flow reads pasted or typed lines until Ctrl-D. Start a nested line with Tab or four spaces:

Learned how project state flows through the editor.
    Traced the command and persistence boundaries.
Added the persistence test.
#learning #done $core-toy

The metadata line is optional. The CLI prints the available tags and stages. Use only space-separated prefixed values: #tag for tags and $stage for one stage. Commas, bare values, and @stage input are rejected.

  Supported metadata input:

  #bug #learning $core-toy

List entries in the current project:

diary list
diary list -f

Filters are combined with AND semantics. Listing across all initialized projects uses -a:

diary list -a
diary list -af

Run commands directly from the checkout while developing:

bun run cli init
bun run cli -l

Configuration

~/.diary/config.json contains default tags/stages, the central notes directory, and project-specific additions:

{
  "defaultConfig": {
    "tags": ["bug", "feature", "learning", "done"],
    "stages": ["core-toy", "protocol"],
    "notesDir": "/home/me/notes"
  },
  "projects": {}
}

Tags and stages are normalized to lowercase kebab-case. Project values extend the defaults and duplicate values are removed.

Development

bun test
bun run typecheck
bun run build

The example Markdown fixtures are in docs/example-log-md-files.

License

MIT. See LICENSE.