bujo

A CLI bullet journal. JSON source of truth, Markdown export for Obsidian.

Quick Start

# Build and install to ~/.local/bin
make install

# Initialize a new bujo data directory
bujo init

# Add your first task
bujo add "Try out bujo"

# See today's log
bujo list

Install

# Build + install to ~/.local/bin (must be on PATH)
make install

# Or build only (binary stays in repo root)
make build

# Uninstall
make uninstall

Requires Go 1.21+. No other dependencies.

Makefile Targets

  build          Build the bujo binary
  install        Build and install to ~/.local/bin
  uninstall      Remove installed binary
  test           Run all tests (verbose)
  test-short     Run tests without verbose output
  test-cover     Run tests with coverage report
  vet            Run go vet
  lint           Run all static checks
  clean          Remove build artifacts
  run            Build and run with args: make run ARGS="add 'Buy milk'"
  version        Show version that would be embedded
  help           Show this help

Usage

Daily Entries

# Add a task (default type)
bujo add "Fix sprinkler zone 3"

# Add with priority flag
bujo add --priority "Schedule quarterly review"

# Add an event with date and time
bujo add --type event --date 2026-03-30 --time "14:00" "Dentist appointment"

# Add a note
bujo add --type note "Interesting article about Go generics"

# Add with tags
bujo add --tags "infra,devops" "Fix backup script errors"

# Add to a specific date (not today)
bujo add --date 2026-03-25 "Retroactive note about Monday"

View Entries

# Today's log
bujo list

# Specific date
bujo list --date 2026-03-25

# Date range
bujo list --from 2026-03-24 --to 2026-03-28

# Filter by type and status
bujo list --type task --status open

Task Lifecycle

# Complete a task (use UUID prefix)
bujo complete a1b2c3

# Cancel a task
bujo cancel a1b2c3

# Migrate to another date (tracks migration history)
bujo migrate a1b2c3 --to 2026-03-30

# Migrate to the future log
bujo migrate a1b2c3 --to-future --target-month 2026-04

Stale Task Detection

# Find tasks that keep getting pushed (3+ migrations or 5+ days open)
bujo stale

# Custom thresholds
bujo stale --days 7 --migrations 4

Search

# Search across all entries
bujo search "sprinkler"

# Limit to a scope
bujo search --scope daily "sprinkler"
bujo search --scope future "taxes"
bujo search --scope collections "birthday"

Monthly Logs

# Show current month's goals and theme
bujo monthly show

# Set goals and theme
bujo monthly set --month 2026-03 \
  --theme "Ship Conduit v2" \
  --goals "Finish bujo tool" --goals "Deploy federation"

# Add end-of-month reflection
bujo monthly set --month 2026-03 \
  --reflection "Solid month. Bujo rework shipped."

Future Log

# List all future items
bujo future list

# Add a future item
bujo future add "File 2025 federal taxes" --date 2026-04-15 --priority

# Complete a future item
bujo future complete a1b2c3

Collections

# List all collections
bujo collection list

# View entries in a collection
bujo collection show birthdays

# Add an entry (JSON object)
bujo collection add birthdays '{"name":"Alice","date":"2025-06-15","relation":"friend"}'

# Create a new collection
bujo collection create "home-projects" --description "House improvement backlog"

Export to Obsidian

# Export everything to Obsidian (path from config.json)
bujo export

# Export to a specific path
bujo export --target /path/to/obsidian/BuJo

# Export only daily logs
bujo export --scope daily

# Preview without writing
bujo export --dry-run

Data Directory

Default: ~/.bujo/ (override with --dir flag or BUJO_DIR env var).

~/.bujo/
├── daily.json          # daily log entries (tasks, events, notes)
├── monthly.json        # monthly goals, themes, reflections
├── future.json         # forward-looking items
├── collections.json    # index of collection topics
├── collections/        # one JSON file per topic
│   ├── birthdays.json
│   └── bills.json
└── config.json         # export target, nag thresholds

The data directory is a git repository. Every mutation auto-commits.

Design Principles

• JSON is the source of truth — never parse Markdown
• Obsidian Markdown is a one-way export — generated, never read back
• Every mutation auto-commits to the local git repo
• Markdown output by default — use --json for scripting
• Self-documenting — every command has --help with examples
• No external dependencies — just Go stdlib + Cobra

AI Agent Integration

The skill/ directory contains a Conduit-compatible SKILL.md that maps natural language intents to CLI commands. Drop skill/SKILL.md into your agent's skill search path to enable BuJo management via conversational AI.

Global Flags

Flag	Env Var	Default	Description
--dir	BUJO_DIR	~/.bujo	Data directory path
--json	—	false	Output as JSON instead of Markdown
--quiet	—	false	Suppress non-essential output
--verbose	—	false	Verbose output

License

MIT