Repository avatar
AI Tools
v2.0.1
active

devlog

io.github.SpIob/devlog

Offline developer journal with local-LLM digests, semantic search, and MCP server.

Documentation

devlog-cli

CI PyPI Python License: MIT

A terminal-based developer journal — log, search, filter, and export daily progress entries without leaving the command line. Local-AI powered: weekly digests, semantic search, and an MCP server for AI agents, all fully offline.


Demo

devlog-cli demo — add, list, search, stats, calendar heatmap, and semantic ask


Installation

With pipx (recommended — keeps devlog isolated):

pipx install devlog-tool

With pip:

pip install devlog-tool

With the ai extra (documents the AI tier — digest/ask/mcp; the features are built in and stdlib-only, you just need a local Ollama server for --llm and ask):

pipx install "devlog-tool[ai]"
ollama pull llama3.2 nomic-embed-text

From source:

pipx install git+https://github.com/SpIob/devlog-cli.git

After installation, the devlog command is available globally in your terminal.

Requires Python 3.10+.


Switching from jrnl / Day One

Already journaling? Bring your history with you — the importers are built in:

devlog import ~/.jrnl/journal.json        # jrnl JSON export (format auto-detected)
devlog import ~/Downloads/Day\ One.json   # Day One JSON export (format auto-detected)

Tags and timestamps carry over, Day One uuids are preserved as entry ids, and re-importing the same file is a no-op (entries dedupe by id or a (created_at, message) fingerprint) — you can switch without a cliff.

devlogjrnlDay Oneplain notes
Runs fully offline✓✓✓✓
No account, no cloud✓✓—✓
Built-in MCP server for AI agents✓———
Semantic search via local LLM (ask)✓———
Offline weekly digests✓———
Git-native entries (--from-commit)✓———
Streaks, tag co-occurrence, calendar heatmap✓———
Tags + date/tag filtering✓✓✓—

Quick Start

# Log what you did this morning
devlog add "Set up staging environment on Railway" -t devops

# Add an entry with multiple tags
devlog add "Fixed off-by-one error in pagination logic" -t bugfix -t backend

# Review today's work
devlog list

# Find everything related to your auth work
devlog search "auth"

# Narrow list output to a specific tag
devlog list -t bugfix

# Show the full text of a single entry by ID
devlog show a1b2c3d4

# Edit a typo in an entry's message
devlog edit a1b2c3d4 -m "Corrected message text"

# Backdate a forgotten entry
devlog add "Wrote the README yesterday" --at "2h"

# Delete an entry (prompts for confirmation; use -y to skip)
devlog delete a1b2c3d4 -y

# See which tags you use most
devlog tags

# Show all entries with a particular tag
devlog tag backend

# Strip a tag from every entry that has it
devlog tag backend --delete

# Merge two tags (add NEW to entries that have OLD, then remove OLD)
devlog merge-tag backend devops

# See what you logged today / yesterday
devlog today
devlog yesterday

# See the last 7 days
devlog week

# See the 10 most recent entries
devlog tail 10

# Get a quick journal summary with a 30-day sparkline
devlog stats

# See a year-grid heatmap of activity
devlog calendar

# Rename a tag across every entry
devlog rename-tag backend devops

# Customize the colors (optional)
devlog theme show > ~/.devlog/theme.toml
$EDITOR ~/.devlog/theme.toml
devlog theme set ~/.devlog/theme.toml

# Import entries from an exported Markdown file
devlog import ~/notes/old-log.md

# Launch the interactive REPL
devlog --interactive

# Export everything to a Markdown file for your weekly review
devlog export -o ~/notes/week-20.md

Command Reference

devlog add

Add a new journal entry.

devlog add MESSAGE [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
MESSAGE—stringYes—The body of the journal entry.
--tag-tstringNo—Attach a tag to the entry. Repeatable: -t backend -t bugfix. Tags are normalized to lowercase. Allowed characters: [a-z0-9-].
--at—stringNo—Backfill the entry with a custom created_at. Accepts absolute timestamps (YYYY-MM-DD, YYYY-MM-DDTHH:MM, …Z) and relative ones (2h, 30m ago). With DEVLOG_TZ set, naive inputs are interpreted in that zone.
--quiet-qflagNoFalseSuppress confirmation output. Exits silently with code 0 on success.

Notes:

  • Tag validation: see Tag rules.
  • An empty message string exits with code 1.

Examples:

devlog add "Finished OAuth2 integration"
devlog add "Refactored database connection pool" -t backend -t refactor
devlog add "Deployed hotfix to production" -t devops -q
devlog add "Wrote the README yesterday" --at "2h"
devlog add "Logged a meeting from 9am" --at "2025-08-28T09:00:00Z"

devlog list

Display journal entries in a formatted table, newest first.

devlog list [OPTIONS]
OptionShortTypeDefaultDescription
--tag-tstringNoneFilter by tag. Repeatable. Multiple flags use AND logic — entry must carry all specified tags.
--limit-ninteger20Maximum number of entries to display. Must be a positive integer.
--all—flagFalseOverride --limit and display every entry.
--since—stringNoneOnly show entries on or after this date. See Date filters.
--until—stringNoneOnly show entries on or before this date. See Date filters.
--quiet-qflagFalseOutput one raw JSON object per line to STDOUT instead of the Rich table. Useful for scripting.

Notes:

  • Results are sorted newest first.
  • Message text is truncated to 60 characters with a … suffix in table view.
  • If no entries exist, prints No entries found. and exits with code 0.
  • If filters are applied and nothing matches, prints No entries match your filters. and exits with code 0.

Examples:

devlog list
devlog list -t bugfix
devlog list -t backend -t auth --limit 5
devlog list --all
devlog list --since 2025-01-01 --until 2025-12-31
devlog list --since 7d
devlog list --quiet | jq '.tags'

devlog search

Full-text search across all entry messages.

devlog search QUERY [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
QUERY—stringYes—Search term. Case-insensitive substring match against the message field. Multiple space-separated terms require ALL of them (AND). Wrap a phrase in quotes to match it exactly. With --regex, QUERY is a regular expression.
--tag-tstringNoNoneNarrow results to entries that also carry these tags. Repeatable; AND logic.
--limit-nintegerNo20Maximum number of results to display.
--since—stringNoNoneOnly show entries on or after this date. See Date filters.
--until—stringNoNoneOnly show entries on or before this date. See Date filters.
--regex—flagNoFalseInterpret QUERY as a case-insensitive regular expression. Invalid patterns exit with code 2.
--quiet-qflagNoFalseOutput raw JSON lines to STDOUT instead of the Rich table.

Notes:

  • Matching substrings are highlighted in bold yellow in the Message column (single-term queries only; highlighting is skipped for multi-term and regex queries).
  • An empty or whitespace-only QUERY is rejected with QUERY cannot be empty. and exits with code 1.
  • If no results are found, prints No entries matched "<query>". and exits with code 0.
  • Tag filters and the search term both apply simultaneously (AND logic).

Examples:

devlog search "null pointer"
devlog search auth login              # AND: both terms required
devlog search "login bug" auth        # quoted phrase + term
devlog search "^Fix bug #[0-9]+$" --regex
devlog search "cache" -t backend
devlog search "deploy" --limit 10
devlog search "refactor" --since 7d
devlog search "refactor" --quiet | jq '.'

devlog on

Show entries for a specific date — the missing sibling of today / yesterday / week.

devlog on DATE [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
DATE—stringYes—today, yesterday, Nd (N days ago, e.g. 3d), or an absolute YYYY-MM-DD.
--limit-nintegerNo50Maximum entries to show.
--quiet-qflagNoFalseOutput raw JSON lines.

Notes:

  • The day bucket is the local date when DEVLOG_TZ is set, otherwise UTC — same rule as today/yesterday/week.
  • An unparseable DATE exits with code 2.

Examples:

devlog on today
devlog on yesterday
devlog on 3d                # three days ago
devlog on 2025-05-10

devlog show

Display a single entry in full detail (no message truncation).

devlog show ID
Argument / OptionShortTypeRequiredDefaultDescription
ID—stringYes—The 8-char short id, the full UUID, or a unique prefix of either.
--quiet-qflagNoFalseOutput a single raw JSON line instead of the panel.

Notes:

  • If the prefix matches more than one entry, the command exits with code 1 and lists the candidate short ids.
  • The full message is shown (no 60-char truncation).
  • Updated displays — for entries that have never been edited, otherwise the timestamp of the most recent edit.

Examples:

devlog show a1b2c3d4
devlog show a1b2
devlog show a1b2c3d4-e5f6-7890-abcd-ef1234567890 --quiet

devlog edit

Edit an entry's message and/or tags in place. Preserves the original created_at (unless --at is supplied) and sets updated_at on success.

devlog edit ID [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
ID—stringYes—The 8-char short id, the full UUID, or a unique prefix.
--message-mstringNo—Replace the message text.
--tag-tstring, repeatableNo—Replace the tag set with this list. Existing tags are discarded.
--add-tag—string, repeatableNo—Append tags to the existing set. Duplicates are silently dropped.
--remove-tag—string, repeatableNo—Remove tags from the existing set.
--at—stringNo—Replace the entry's created_at. Same format as add --at. Prompts for confirmation unless --yes is also passed.
--yes-yflagNoFalseSkip the --at confirmation prompt.
--quiet-qflagNoFalseSuppress confirmation output.

Notes:

  • If no flag is passed, the entry's current message is opened in $VISUAL / $EDITOR (falling back to nano or vi if neither is set). Save and exit to apply the edit; abort to discard. This requires a TTY; in a non-interactive shell (CI, scripts, output captured to a file), edit with no flags errors out instead of dumping terminal escapes. Set DEVLOG_ALLOW_EDITOR_IN_PIPE=1 to opt in to the old behaviour.
  • An empty --message is rejected with the same MESSAGE cannot be empty error as devlog add. The editor path is allowed to produce an empty body, since the user may want to save a blank note on purpose.
  • No-op edits (the result equals the existing entry) print No changes. and exit 0 without touching the file.
  • Tag flags combine: --tag runs first, then --add-tag adds, then --remove-tag removes.
  • Validation rules for tag characters and length: see Tag rules.

Examples:

devlog edit a1b2c3d4 -m "Corrected typo in the original entry"
devlog edit a1b2c3d4 --add-tag urgent
devlog edit a1b2c3d4 --remove-tag docs --add-tag refactor
devlog edit a1b2c3d4     # opens $EDITOR with the current message
devlog edit a1b2c3d4 --at "2025-08-28T09:00:00Z" --yes   # re-time without prompt

devlog delete

Delete an entry by id.

devlog delete ID [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
ID—stringYes—The 8-char short id, the full UUID, or a unique prefix.
--yes-yflagNoFalseSkip the confirmation prompt.
--quiet-qflagNoFalseSuppress the success panel.
--ignore-missing—flagNoFalseExit 0 (not 1) when the given ID does not exist. Useful in scripts where delete should be idempotent.

Notes:

  • By default, the command asks for confirmation ([y/N]). Decline to abort without changes; confirm to delete and render a red-bordered panel.
  • Deletion is atomic — the JSON file is rewritten via the same temp-file + os.replace() pattern as every other write.

Examples:

devlog delete a1b2c3d4              # confirm interactively
devlog delete a1b2c3d4 -y           # skip prompt
devlog delete a1b2 -y               # delete by unique prefix
devlog delete a1b2c3d4 -y --ignore-missing   # idempotent: no error if absent

devlog tags

List all distinct tags with their usage count and the most recent date they were used.

devlog tags [OPTIONS]
OptionShortTypeDefaultDescription
--sort—choicecountOne of count (most-used first), name (alphabetical), or recent (most recently used first).
--limit-ninteger50Maximum number of tags to show.
--all—flagFalseOverride --limit and show every tag.
--quiet-qflagFalseOutput {tag, count, last_used} JSON lines instead of the table.

Notes:

  • Last used is the more recent of the entry's created_at and updated_at, so editing a tag keeps its timestamp fresh.
  • Empty state: prints No tags found. and exits 0.

Examples:

devlog tags
devlog tags --sort name
devlog tags --limit 10
devlog tags --quiet | jq '.tag'

devlog theme

View or change the active color theme. Themes live in ~/.devlog/theme.toml (or $DEVLOG_DATA_DIR/theme.toml when set) and override individual color roles. See the Themes section for the full list of roles and a starter file.

devlog theme SUBCOMMAND
SubcommandDescription
devlog theme listPrint every role and its current style as a two-column table (with section grouping and preview swatches by default).
devlog theme show [ROLE]Print the value of a single role, or dump a starter theme.toml (all roles commented out) to STDOUT.
devlog theme set PATHValidate and install a theme file as the active theme. Unknown roles are dropped with a warning. Add --check to validate without installing.
devlog theme use NAMEInstall a bundled theme by name (e.g. devlog theme use dracula). Use devlog theme use default to reset to the built-in defaults.
devlog theme builtinsList all bundled theme names with their short description.
devlog theme resetRemove the active theme file and fall back to the defaults. Prompts for confirmation.
devlog theme editOpen the active theme file in $VISUAL/$EDITOR. Creates a starter template if no file exists yet.
devlog theme createInteractively walk through every role, preview the palette, and install it as the active theme (or write to --output PATH).
devlog theme diffShow the active theme's overrides relative to the built-in defaults. With --default, inverts to show roles that still match the defaults.
devlog theme exportWrite the active palette as a complete, uncommented theme.toml to --output PATH or --stdout.
devlog theme pathPrint the absolute path to the active theme file.

Notes:

  • theme list accepts --flat (disable section grouping) and --no-preview (hide the preview swatch column).
  • theme set accepts --check to validate a theme file without installing it (exits 1 on any error).
  • theme create accepts --from BUNDLED_NAME to seed values from a built-in theme, --name/--description for [meta], --output PATH to write to a file instead of installing, and --install/--no-install to control installation explicitly.
  • theme export requires exactly one of --stdout or --output PATH.

Examples:

# See every color role (grouped, with preview swatches)
devlog theme list
devlog theme list --flat --no-preview   # compact, single column

# Read a single role's value
devlog theme show date
# → cyan

# Generate a starter theme file you can edit
devlog theme show > ~/my-theme.toml
$EDITOR ~/my-theme.toml   # uncomment and tweak the roles you want to change
devlog theme set ~/my-theme.toml
devlog theme set ~/my-theme.toml --check   # validate only, don't install

# Try a bundled theme
devlog theme builtins
devlog theme use dracula
devlog theme use default                   # reset to built-in defaults

# Find the active theme path (useful for `ln -s` workflows)
devlog theme path
# → /Users/you/.devlog/theme.toml

# Edit the active theme in your $EDITOR
devlog theme edit

# Build a new theme interactively
devlog theme create --from nord --name "My Nord Variant"
devlog theme create --output ~/my-theme.toml --no-install

# Audit your overrides
devlog theme diff          # show only roles that differ from defaults
devlog theme diff --default    # show only roles that still match defaults

# Export the active palette
devlog theme export --output ~/devlog-palette.toml
devlog theme export --stdout > ~/devlog-palette.toml

devlog today

Show entries created today, newest first.

devlog today [OPTIONS]
OptionShortTypeDefaultDescription
--limit-ninteger50Maximum entries to show.
--quiet-qflagFalseOutput raw JSON lines instead of a table.

Notes:

  • "Today" is computed in the local zone when DEVLOG_TZ is set, otherwise UTC. Set DEVLOG_TZ=America/New_York to make today, yesterday, and week reflect your wall clock.
  • Empty state: prints No entries yet today. and exits 0.

Examples:

devlog today
devlog today --limit 5
devlog today --quiet

devlog yesterday

Show entries created yesterday, newest first. Same local-tz semantics as today.

devlog yesterday [OPTIONS]
OptionShortTypeDefaultDescription
--limit-ninteger50Maximum entries to show.
--quiet-qflagFalseOutput raw JSON lines instead of a table.

Examples:

devlog yesterday
devlog yesterday --quiet

devlog week

Show entries from the last 7 days, newest first. The window ends on today (or the --day anchor) and spans the 6 days before it.

devlog week [OPTIONS]
OptionShortTypeDefaultDescription
--limit-ninteger100Maximum entries to show.
--day—string (YYYY-MM-DD)todayAnchor day; the week ends on this day and includes the 6 days before it.
--quiet-qflagFalseOutput raw JSON lines instead of a table.

Examples:

devlog week
devlog week --day 2025-05-10
devlog week --limit 20 --quiet

devlog tail

Show the N most recent entries (default 5), newest first.

devlog tail [N] [OPTIONS]
Argument / OptionShortTypeDefaultDescription
N—integer5Number of entries to show.
--tag-tstring, repeatableNoneFilter by tag (AND logic).
--quiet-qflagFalseOutput raw JSON lines.

Examples:

devlog tail        # last 5
devlog tail 20
devlog tail 10 -t bugfix

devlog stats

Show a one-glance summary of the journal: totals, date range, current and longest writing streaks, top tags and tag pairs, days since the last entry, and a 30-day sparkline of entries per day.

devlog stats [OPTIONS]
OptionShortTypeDefaultDescription
--quiet-qflagFalseOutput a single JSON object with the summary.
--since—stringNoneOnly include entries on or after this date. See Date filters.
--until—stringNoneOnly include entries on or before this date. See Date filters.

Notes:

  • The sparkline is an ASCII bar (▁–█) representing entries per day for the last 30 days. The window and date range are computed in the local zone when DEVLOG_TZ is set, otherwise UTC.
  • The First / Last / Span lines render in the local zone when DEVLOG_TZ is set (the … UTC suffix becomes the zone's key, e.g. … EST).
  • The Streak line shows your current consecutive-day streak (counted back from today; writing yesterday but not today keeps it alive) plus the longest streak in journal history. Last entry: N days ago is the nudge line.
  • Top tag pairs lists the tag co-occurrences — the two tags most often written on the same entry.
  • --quiet adds streaks ({"current": N, "longest": N}), top_tag_pairs ([{"tags": [a, b], "count": N}]), and days_since_last to the JSON object.
  • Empty state: prints No entries to summarize. and exits 0.

Example output:

╭─ Journal Stats ─────────────────────────────────────────╮
│                                                       │
│  Total     : 142                                      │
│  First     : 2025-04-12 09:14 UTC                     │
│  Last      : 2026-08-29 11:02 UTC                     │
│  Span      : 139 days                                 │
│  Avg/day   : 1.02                                     │
│                                                       │
│  Top 5 tags                                           │
│    backend : 41                                       │
│    bugfix  : 28                                       │
│    docs    : 17                                       │
│    devops  : 12                                       │
│    refactor: 9                                        │
│                                                       │
│  Last 30 days (entries per day)                          │
│  ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█▁▁█▁█                     │
╰───────────────────────────────────────────────────────╯

Examples:

devlog stats
devlog stats --quiet | jq '.total, .top_tags'

devlog tag

Show entries that carry a tag, or strip a tag from every entry that has it. (No entries are deleted by --delete.)

devlog tag NAME [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
NAME—stringYes—The tag to inspect. Normalised to lowercase.
--delete—flagFalseStrip the tag from every entry that has it (prompts for confirmation; use -y to skip).
--yes-yflagFalseWith --delete: skip the confirmation prompt.
--dry-run—flagFalseWith --delete: show what would change without writing.
--limit-ninteger20Show mode: max entries to list.
--all—flagFalseShow mode: override --limit and list every entry.
--quiet-qflagFalseOutput raw JSON lines (or suppress the success line under --delete).

Notes:

  • NAME is validated with the same rules as devlog add — see Tag rules.
  • devlog tag NAME --delete asks Remove tag "NAME" from N entries? by default — pass -y/--yes to skip, or combine with --quiet to skip the prompt in scripts.
  • devlog tag NAME --delete --dry-run previews the change without writing.
  • Use devlog merge-tag A B if you want to combine two tags instead of just inspecting or removing one.

Examples:

devlog tag backend
devlog tag backend --limit 5
devlog tag backend --delete -y
devlog tag backend --delete --dry-run

devlog calendar

Show a year-grid heatmap of journal activity. Each cell is one day; the colour tier reflects the entry count for that day.

devlog calendar [OPTIONS]
OptionShortTypeDefaultDescription
--year—integercurrent yearYear to render.
--quiet-qflagFalseOutput a {YYYY-MM-DD: count} JSON map for the year.

Notes:

  • The grid uses the heatmap_empty / heatmap_l1 … heatmap_l4 theme roles. See Themes to restyle.
  • The bucketing date is the local date when DEVLOG_TZ is set, otherwise UTC. With DEVLOG_TZ=America/New_York, an entry at 02:00 UTC on Jan 1 lands in Dec 31's cell.
  • Empty state: prints No entries in <year>. and exits 0.

Examples:

devlog calendar
devlog calendar --year 2024
devlog calendar --year 2024 --quiet | jq

devlog rename-tag

Rename a tag across every entry in the journal (bulk replace).

devlog rename-tag OLD NEW [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
OLD—stringYes—The existing tag to replace.
NEW—stringYes—The new tag name. Validated as a tag (see Tag rules).
--dry-run—flagNoFalseShow the count of affected entries without writing.
--quiet-qflagNoFalseSuppress the success line.

Notes:

  • Every entry that contains OLD is rewritten in place. The entry's created_at is preserved and updated_at is set to the current UTC time.
  • If an entry already carries NEW, the result is deduplicated so no entry ends up with the same tag twice.
  • If no entries carry OLD, prints No entries with tag "<old>". and exits 0.
  • NEW is validated against the tag rules (see Tag rules) and rejected with a clear error if it would be invalid. (Older versions used to silently no-op when the lowercased NEW happened to equal OLD — that path is fixed.)

Examples:

devlog rename-tag backend devops
devlog rename-tag bugfix fix --dry-run

devlog merge-tag

Merge OLD into NEW across every entry: every entry that has OLD gets NEW added (deduplicated) and OLD removed. Entries that already carry NEW are not double-tagged.

devlog merge-tag OLD NEW [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
OLD—stringYes—The tag to retire.
NEW—stringYes—The tag to consolidate into. Validated as a tag (see Tag rules).
--dry-run—flagFalseShow the count of affected entries without writing.
--quiet-qflagFalseSuppress the success line.

Notes:

  • If OLD.lower() == NEW.lower() after normalisation, the command prints OLD and NEW are the same ("…"). No changes made. and exits 0.
  • If no entries carry OLD, prints No entries with tag "OLD". and exits 0.
  • For a pure rename use devlog rename-tag. For stripping a tag entirely, use devlog tag <name> --delete.

Examples:

devlog merge-tag backend devops
devlog merge-tag bugfix fix --dry-run

devlog import

Import entries from a JSON file (the native entries.json shape), from a Markdown file produced by devlog export, or from a jrnl or Day One JSON export.

devlog import PATH [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
PATH—pathYes—Input file. Must exist and be readable.
--format-fchoiceautoOne of auto, json, markdown, jrnl, dayone. auto picks by file extension, then by content sniffing.
--dry-run—flagFalseShow what would be imported without writing.
--quiet-qflagFalseSuppress the summary line.

Notes:

  • Re-importing the same file is safe and idempotent: entries are recognised by their existing id (when present in the source) or by their (created_at, message) fingerprint, so the second import is a no-op.
  • Stable id values in the source JSON are preserved across re-imports, so a devlog export → devlog import round-trip keeps short ids stable for cross-referencing. If the source row omits id, devlog mints a fresh one.
  • Unreadable rows in a JSON import (non-dict items or entries missing required fields) are reported in the summary line as Ignored N unreadable rows.
  • Auto-detect sniffs the first non-blank character when the file extension is missing, so pipes and extensionless files work: leading { → JSON, leading # → Markdown.
  • jrnl format: an object with an entries array whose items carry text/date/starred. text becomes the message, date (naive timestamps are treated as UTC) becomes created_at, tags carry over, and a starred entry gains a starred tag. Re-imports dedupe by fingerprint since jrnl rows have no stable ids.
  • Day One format: an object with an entries array whose items carry creationDate/text. The Day One uuid is preserved as the entry id; tags are lowercased with spaces converted to hyphens.
  • If the file format cannot be detected and --format was not given, exits with code 2.
  • Malformed JSON or markdown that contains no ## … headings exits with code 2.

Examples:

devlog import ~/notes/old-log.md
devlog import /tmp/entries.json --format json
devlog import ~/.jrnl/journal.json --format jrnl     # or just: devlog import ~/.jrnl/journal.json
devlog import ~/Downloads/Day\\ One.json              # auto-detects Day One
devlog import /tmp/entries.json --dry-run

devlog git

Git integration for keeping your journal inside a repository (sync + history for free).

devlog git {status|sync|log} [OPTIONS]
CommandOptionTypeDefaultDescription
git status--jsonflagFalseEmit the full status (repo root, branch, remote, clean flag, changed files) as one JSON object.
git sync--message / -mstringdevlog: journal updateCommit message used when changes are found.
git sync--quiet / -qflagFalseSuppress output.
git log--onelineflagFalseOne commit per line.
git log--limit / -ninteger20Maximum commits to show.

Notes:

  • Commands resolve the repository containing your data dir (DEVLOG_DATA_DIR or ~/.devlog) — the data dir itself does not need to be the repo root; a journal subdirectory inside a repo works.
  • git status reports is_git_repo: false (exit 0) when no repository is found.
  • git sync runs git add -A + git commit only when git status --porcelain is non-empty; a clean repo is a no-op. Exits 1 when the data dir is not inside a repository.
  • git log prints the repository's commit log (not filtered to journal files). A repository with no commits exits 1 with git's does not have any commits yet error.

Example recipe — journal inside an existing repo:

# Keep the journal in a private repo and commit after each entry.
export DEVLOG_DATA_DIR="$HOME/Dropbox/devlog-repo"
git -C "$HOME/Dropbox/devlog-repo" init   # once

devlog add "shipped the thing"
devlog git sync                            # commits journal changes
devlog git status                          # dirty state at a glance

Example recipe — auto-commit after every write (shell hook):

# In your shell rc: sync the journal whenever devlog writes to it.
devlog() {
  command devlog "$@" || return $?
  case "$1" in
    add|edit|delete|import|restore|merge-tag|rename-tag) command devlog git sync -q ;;
  esac
}

Git-native entries: devlog add --from-commit

Turn a commit into a journal entry — the message, tags, and timestamp come from the commit itself.

devlog add [NOTE] --from-commit REF
Argument / OptionShortTypeRequiredDefaultDescription
NOTE—stringYes*—Optional note prefixed to the commit subject. Pass an empty string ("") to use the commit message alone. *Required by the parser; "" is the "no note" idiom.
--from-commit—git ref—NoneAny ref git show accepts: HEAD, HEAD~1, a sha, a branch name.
--tag / -t—stringNoNoneExtra tags, merged in front of the ones extracted from the commit.
--at—timestampNoauthor dateOverride the entry timestamp (same formats as a plain add --at).

Notes:

  • Message: the commit subject (first line) is used; a NOTE argument is prefixed as NOTE\n\n<subject>.
  • Tags: a conventional-commit scope (feat(auth): …, fix(api): …) becomes the tag auth/api; a [tag] message prefix also becomes a tag; a commit-<short-hash> tag is always added for cross-referencing back to git log.
  • Timestamp: the commit's author date, normalised to UTC.
  • Must be run inside a git repository; exits 1 outside one or with an unresolvable ref.

Examples:

# Journal the commit you just shipped
devlog add "" --from-commit HEAD

# With a note and extra tags
devlog add "reviewed with the team" --from-commit HEAD~2 -t retro

# Journal the whole day's work from git history
for ref in $(git log --since=midnight --format=%h); do
  devlog add "" --from-commit "$ref" -q
done

devlog completions

Print a shell completion script to STDOUT. Source or install it according to your shell's conventions.

devlog completions {bash|zsh|fish}

Examples:

# bash
devlog completions bash > ~/.bash_completion.d/devlog

# zsh (place in a directory on $fpath)
devlog completions zsh > ~/.zsh/completions/_devlog

# fish
devlog completions fish > ~/.config/fish/completions/devlog.fish

devlog --interactive

Launch a minimal line-based REPL for browsing and adding entries without leaving the prompt.

devlog --interactive
devlog -i
DEVLOG_INTERACTIVE=1 devlog

REPL commands (run help at the prompt to see the up-to-date list — every command in the CLI is available, plus a few aliases):

CommandWhat it does
add <message> [-t tag ...]Add a new entry.
l | list [-t tag] [-n N]List entries.
s | search <query>Search entry messages.
show <id>Show a single entry.
edit <id> [-m msg] [-t tag]Edit an entry.
delete <id> [-y]Delete an entry.
todayShow today's entries.
y | yesterdayShow yesterday's entries.
w | weekShow the current week.
tail [N]Show the N most recent entries.
tagsList tags with usage counts.
statsSummarize the journal.
tag <name>List entries with a tag (or --delete -y to remove the tag from every entry).
merge-tag <old> <new>Rename one tag everywhere.
calendarYear-grid heatmap of journal activity.
themeView or change the active color theme (sub: list, show, set, path, reset, edit, diff, export, use, builtins, create).
rename-tag <old> <new>Rename a tag.
import <path>Import entries.
completions <shell>Print a shell completion script.
export [-o path]Export to Markdown or JSON.
repair [-y] [--dry-run]Inspect and repair the on-disk store.
backup [-o path]Write a timestamped backup.
restore <path>Restore from a backup file.
doctorCheck store health.
h | helpShow the REPL help.
q | quit | exitLeave the REPL.

Notes:

  • Requires a TTY. Outside a TTY the command exits with code 1 and a clear error message. Set DEVLOG_INTERACTIVE_FORCE=1 to bypass the TTY check (useful in tests, scripts, or remote shells).
  • Any other subcommand argument is dispatched to the underlying CLI in-process.

Examples:

devlog --interactive
DEVLOG_INTERACTIVE=1 devlog

devlog export

Export all entries (or a filtered subset) to a Markdown or JSON file.

devlog export [OPTIONS]
OptionShortTypeDefaultDescription
--output-opath<data-dir>/exports/devlog-YYYYMMDD-HHMMSS.<ext>Destination file path. Existing files are overwritten without prompting. When omitted, files land in $DEVLOG_DATA_DIR/exports/ (or ~/.devlog/exports/) rather than the current working directory, so cd-ing around doesn't pollute the cwd.
--format-fauto | markdown | jsonautoOutput format. auto infers from the --output extension (.json → JSON, .md/.markdown → Markdown, anything else → Markdown). Explicit --format wins over the extension.
--tag-tstringNoneExport only entries that carry all specified tags. Repeatable; AND logic.
--since—stringNoneOnly export entries on or after this date. See Date filters.
--until—stringNoneOnly export entries on or before this date. See Date filters.
--quiet-qflagFalseSuppress the progress bar and confirmation. Prints only the output path on success.

Output format per entry:

## 2025-05-11 10:22 UTC — a1b2c3d4

Rewrote auth middleware to use JWT refresh tokens.

**Tags:** backend, security

---

Notes:

  • A Rich progress bar is shown on STDERR during the write (suppress with --quiet).
  • If no entries exist (or no entries match the tag filters), prints Warning: No entries to export. and exits with code 0. No file is created in that case, so you can safely re-run after emptying the journal.
  • If the output path is not writable, exits with code 2 and a clear error message.

Examples:

devlog export
devlog export -o ~/notes/week-20.md
devlog export -t backend -o backend-log.md
devlog export --since 2025-01-01 --until 2025-12-31 -o year.md
devlog export --quiet -o /tmp/devlog.md

devlog repair

Inspect the on-disk journal and, optionally, rewrite it to drop malformed rows. Useful when devlog doctor reports validation issues, or when the file has been hand-edited and broken.

devlog repair [OPTIONS]
OptionShortTypeDefaultDescription
--dry-run—flagFalseShow the issues and what would be dropped, without writing.
--yes-yflagFalseSkip the "drop N entries — continue?" confirmation.
--backup / --no-backup—flag--backupWrite a timestamped backup to <data-dir>/backups/ before the rewrite.
--quiet-qflagFalseSuppress the summary panel.

Notes:

  • A backup is written before the file is rewritten, so you can always undo a repair with devlog restore <backup-file>.
  • Validation rules match the storage contract: every entry must have a non-empty id and message, a parseable created_at (ISO 8601 UTC), and tags that match ^[a-z0-9-]+$ with at most 32 characters.
  • Duplicate ids keep the first occurrence; subsequent duplicates are reported and dropped.
  • Exit code is 0 when nothing was dropped, 1 when entries were dropped.
  • A corrupted JSON file (invalid syntax) is not repairable; the command exits with code 2 and tells you to restore from a backup.

Examples:

# See what's wrong, without writing
devlog repair --dry-run

# Drop invalid rows, writing a backup first
devlog repair -y

# Run the repair non-interactively from a script
devlog repair -y --no-backup

devlog backup

Write a timestamped copy of the journal. The default destination is <data-dir>/backups/entries-YYYYMMDD-HHMMSS.json. The file is a normal entries.json — it can be inspected, edited, and round-tripped through devlog restore.

devlog backup [OPTIONS]
OptionShortTypeDefaultDescription
--output-opath<data-dir>/backups/entries-TIMESTAMP.jsonBackup file path. Parent directories are created if they don't exist.
--quiet-qflagFalsePrint only the backup path (no success panel).

Notes:

  • The backup is just a copy of entries.json (the JSON shape that devlog reads on every startup). It can be inspected, edited, and used as input to devlog restore.
  • Backups are placed under <data-dir>/backups/ by default; that directory is created lazily on first use.
  • Empty journals can be backed up too — the resulting file is {"entries": []}.

Examples:

# Default: timestamped file under the data dir
devlog backup

# Custom path
devlog backup -o ~/archives/devlog-$(date +%F).json

# Scripting: capture the path, then move the file
devlog backup --quiet

devlog undo

Roll the journal back to its state before the last write. Every mutating command (add, edit, delete, tag, merge-tag, rename-tag, import, repair, restore, …) snapshots the previous store into <data-dir>/backups/entries-TIMESTAMP.pre.json before writing — on both the JSON and SQLite backends — so a single devlog undo reverts any of them.

devlog undo [OPTIONS]
OptionShortTypeDefaultDescription
--yes-yflagFalseSkip the confirmation prompt.
--keep—int10Pre-write snapshots to retain after pruning (0 removes all).
--dry-run—flagFalseShow what would be restored, without writing.
--quiet-qflagFalseSuppress the summary output.

Notes:

  • Repeated undo calls step back through recent writes one at a time (each undo consumes its snapshot instead of re-snapshotting the pre-undo state), so no toggle behavior.
  • Pre-write snapshots are pruned to the 10 newest after every undo; manual devlog backup files are never touched or consumed.
  • To redo after an undo, restore a manual backup: run devlog backup before experimenting, then devlog restore <file>.

Examples:

# Oops — that import duplicated everything
devlog undo

# Inspect first
devlog undo --dry-run

# Non-interactive (scripts)
devlog undo -y -q

devlog restore

Replace the current journal with the contents of a backup file. Per-row issues in the backup are skipped with a warning, so a hand-edited or partially-corrupted backup can still be partially restored.

devlog restore PATH [OPTIONS]
Argument / OptionShortTypeRequiredDefaultDescription
PATH—pathYes—Backup file. Must exist and be readable.
--yes-yflagNoFalseSkip the "overwrite current journal?" confirmation.
--dry-run—flagNoFalseValidate the backup and report what would be restored, without writing.
--quiet-qflagNoFalseSuppress the success line.

Notes:

  • A non-empty journal prompts for confirmation by default; pass -y to skip the prompt in scripts.
  • If the backup is structurally invalid (root is not a JSON object, or entries is not a list), the command refuses to restore and exits with code 2.
  • Per-row issues (bad tags, unparseable timestamps, duplicate ids) are reported as warnings and skipped; the rest is restored.
  • Restoring from an empty backup empties the journal — use --dry-run first if you're unsure.

Examples:

devlog restore ~/archives/devlog-2025-01-15.json
devlog restore backups/entries-20260829-080713.json -y
devlog restore some-backup.json --dry-run

devlog doctor

Check the journal store for corruption and report a quick health snapshot: file path, size, entry count, days since the most recent entry, validation issues, and the three longest messages.

devlog doctor [OPTIONS]
OptionShortTypeDefaultDescription
--quiet-qflagFalseOutput a single JSON object with the report.

Notes:

  • Exit code: 0 when the store is clean, 1 when validation issues are found (run devlog repair to fix), 2 when the file is corrupt or unwritable.
  • "Days since last entry" is computed in UTC.
  • The probe writes a one-byte file inside the data dir to confirm write access; it removes the file before exiting.

Example output:

╭─ 🩺 Doctor  ·  all clear ────────────────────────────────────────────────────╮
│ Path  : /Users/you/.devlog/entries.json                                       │
│ Exists: yes                                                                   │
│ Size  : 4.2 KB                                                                │
│ Writable: yes                                                                 │
│ Entries: 142                                                                  │
│ Last entry: today                                                             │
│                                                                               │
│ ✔ No validation issues.                                                       │
│                                                                               │
│ Longest messages:                                                             │
│   • a1b2c3d4… — 248 chars                                                     │
│   • c3d4e5f6… — 192 chars                                                     │
│   • 9f8e7d6c… — 165 chars                                                     │
╰───────────────────────────────────────────────────────────────────────────────╯

Examples:

devlog doctor
devlog doctor --quiet | jq '{ok, entry_count, issues: (.issues | length)}'

devlog digest --week

Summarize recent journal activity. The default is a fully offline, extractive digest — entries grouped by local day with per-entry times, tags, and a tag-totals footer — no model, no network. With --llm the extractive text is handed to a local Ollama model for a written summary.

devlog digest --week [OPTIONS]
OptionShortTypeDefaultDescription
--week—flagTrueSummarize the last 7 days (the only period in this release).
--day—stringtodayAnchor day (YYYY-MM-DD); the week ends on this day and spans the 6 before it.
--llm—flagFalseAlso produce an LLM-written summary via local Ollama.
--model—stringllama3.2Ollama model for --llm.
--quiet-qflagFalsePrint the digest text only (no header).
--json—flagFalseOutput one JSON object: {week_start, week_end, entry_count, digest}.

Notes:

  • Without --llm, nothing leaves the machine and no model needs to be installed.
  • --llm (or DEVLOG_AI=1) requires a running Ollama server; when it cannot be reached, devlog prints an actionable error and exits 1.
  • An empty week prints an info line and exits 0.

Examples:

devlog digest --week                     # extractive, offline
devlog digest --week --llm               # local LLM-written summary
devlog digest --week --llm --model gemma3:12b
devlog digest --week --json | jq -r .digest

devlog ask

Search the journal semantically using local embeddings: devlog ask "what did I do on auth?" finds entries by meaning, not just keywords. On first run the whole journal is embedded once (via local Ollama) and cached in <data-dir>/embeddings.json; later runs only embed new entries and the query.

devlog ask "QUERY" [OPTIONS]
OptionShortTypeDefaultDescription
--top-nint5Max matches to show.
--json—flagFalseOutput {"query", "results": [{id, message, created_at, score}, …]} sorted by descending score.
--model—stringnomic-embed-textEmbedding model. Changing it (or DEVLOG_EMBED_MODEL) triggers a one-time index rebuild.

Notes:

  • Requires a running Ollama server (the query and any new entries are embedded per call).
  • The index is storage-backend-agnostic: it lives in its own file next to the journal, so it works identically on the json and sqlite backends.
  • Stale index entries (ids no longer in the journal) are pruned automatically.

Examples:

devlog ask "what did I do on auth?"
devlog ask "database migration" --json | jq '.results[0]'
devlog ask "deployments" --top 3

devlog mcp

Expose the journal to AI agents over the Model Context Protocol: newline-delimited JSON-RPC 2.0 on stdio, implemented with the Python stdlib only. Tools: list_entries (optional tag filter and limit), search_entries (case-insensitive substring), add_entry (message required, tags optional), and get_stats (totals, date range, top tags). Tool failures use the MCP isError convention — the server loop never crashes.

devlog mcp [--check]
OptionShortTypeDefaultDescription
--check—flagFalsePrint server info as JSON and exit (sanity check).

Example mcpServers block (Claude Desktop, Hermes, OpenCode, Continue.dev):

{
  "mcpServers": {
    "devlog": {
      "command": "devlog",
      "args": ["mcp"]
    }
  }
}

Example session:

$ echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_stats","arguments":{}}}' | devlog mcp
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "{\"total\": 42, ...}"}], "isError": false}}

Tag rules

Every command that accepts tags (add, edit, tag, rename-tag, merge-tag, plus the --tag filter on list / search / tail / export) applies the same rules:

  • Character set: ^[a-z0-9-]+$ — lowercase letters, digits, and hyphens. Other characters (uppercase, underscores, spaces, punctuation) are rejected.
  • Length: ≤ 32 characters per tag.
  • Count: ≤ 10 distinct tags per entry.
  • Normalisation: whitespace is stripped and the result is lowercased before storage, so Backend is stored as backend. Duplicate tags on the same entry are silently deduplicated.
  • Storage: tags are stored verbatim (already normalised) and rendered as a comma-separated list in tables and panels.

These rules are enforced at every boundary; a tag that violates them is rejected with a clear error and the command exits with code 1 before any file I/O happens.


Date filters

devlog list, devlog search, devlog export, and devlog stats all accept --since and --until flags. Bounds are inclusive: --until 2025-01-15 includes entries written on January 15th.

FormatMeaning
YYYY-MM-DDThat date at 00:00 UTC. As an upper bound, includes the whole day.
YYYY-MM-DDTHH:MMISO 8601, treated as UTC if no offset.
YYYY-MM-DDTHH:MM:SSZISO 8601 with explicit UTC.
YYYY-MM-DD HH:MMSpace-separated form, same semantics as T.
todayToday at 00:00 UTC.
yesterdayYesterday at 00:00 UTC.
NdN days ago at 00:00 UTC (e.g. 7d, 30d).
NwN weeks ago at 00:00 UTC (e.g. 1w, 2w).

Both bounds may be combined. Entries with unparseable timestamps are silently dropped when any bound is set, since a date filter is meaningless for them.

Examples:

# Everything logged in 2025
devlog list --since 2025-01-01 --until 2025-12-31

# Last 7 days, as JSON
devlog list --since 7d --quiet

# Stats for Q1
devlog stats --since 2025-01-01 --until 2025-03-31

# Export last month
devlog export --since 30d -o month.md

Configuration

DEVLOG_DATA_DIR

By default, devlog stores all entries at:

~/.devlog/entries.json

To store entries in a different location — for example, inside a synced folder or a project directory — set the DEVLOG_DATA_DIR environment variable. devlog will read and write entries.json inside whatever directory you specify.

# Store entries in a Dropbox-synced folder
export DEVLOG_DATA_DIR="$HOME/Dropbox/devlog"
devlog add "Entry goes here"
# → written to ~/Dropbox/devlog/entries.json

# Store entries in a project-local directory
export DEVLOG_DATA_DIR="$(pwd)/.devlog"
devlog list

The target directory is created automatically on first run if it does not exist.

You can make the variable permanent by adding it to your shell configuration:

# ~/.zshrc or ~/.bashrc
export DEVLOG_DATA_DIR="$HOME/Dropbox/devlog"

DEVLOG_BACKEND

Select the storage backend: json (default) or sqlite.

export DEVLOG_BACKEND=sqlite
devlog add "hello from SQLite"
json (default)sqlite
Store<data-dir>/entries.json<data-dir>/entries.db
Write patternFull-file rewrite (atomic tmp + os.replace)Single-row INSERT/UPDATE/DELETE in a transaction
ConcurrencyCross-process flock/msvcrt lockingWAL journal mode + 5s busy timeout
Sweet spotJournals up to ~10k entries10k+ entries, multiple simultaneous processes
Corrupt-file recoveryrepair right-truncation recoveryNot applicable (live database with its own crash safety)

Notes:

  • Both backends implement the same command surface; switch by changing the env var — no migration command needed.
  • backup always writes a JSON snapshot regardless of backend, so backup → switch backend → restore migrates a journal between backends:
# Migrate JSON → SQLite
DEVLOG_BACKEND=json devlog backup -q            # prints the snapshot path
export DEVLOG_BACKEND=sqlite
devlog restore <path-from-above> -y
  • doctor and repair are backend-aware and report the active store's path and health.

DEVLOG_TZ

Set an IANA time-zone name (e.g. America/New_York, Europe/Berlin) to make time-bucketed commands reflect your wall clock instead of UTC. When set:

  • today, yesterday, week, stats, and calendar bucket entries by local date.
  • --since / --until and Nd / Nw are interpreted at local midnight and converted to UTC for the comparison.
  • stats renders the First / Last / Span lines with the zone's key suffix (e.g. … EST) instead of … UTC.
  • add --at "2025-08-28 09:00" and edit --at "2025-08-28 09:00" (no offset) are interpreted in this zone.

On-disk timestamps are always UTC, regardless of this setting.

export DEVLOG_TZ="America/New_York"
devlog today          # → entries from today in New York
devlog stats          # → date range rendered in EST
devlog list --since 7d   # → last 7 local days

A bad zone name surfaces a red error and exit 1, never a silent fallback to UTC:

$ DEVLOG_TZ="Not/A_Real_Zone" devlog today
Error: Invalid DEVLOG_TZ "Not/A_Real_Zone": …

DEVLOG_AI, DEVLOG_OLLAMA_HOST, DEVLOG_EMBED_MODEL

Control the AI tier (digest --llm, ask). All three have working defaults; nothing here is required for the offline extractive digest.

VariableDefaultPurpose
DEVLOG_AIunsetSet to 1 to make digest --week produce an LLM summary by default (same as passing --llm each time).
DEVLOG_OLLAMA_HOSThttp://127.0.0.1:11434Ollama server URL — point it at another machine on your LAN (e.g. http://odysseus:11434) if the model does not run locally.
DEVLOG_EMBED_MODELnomic-embed-textEmbedding model for ask. Changing it triggers a one-time index rebuild.
# Local LLM summary using the machine on your desk
export DEVLOG_AI=1
export DEVLOG_OLLAMA_HOST="http://odysseus:11434"
devlog digest --week

Model requirements: digest --llm needs a generation model (default llama3.2; the summary quality scales with the model, gemma3:12b works well). ask needs an embedding model (default nomic-embed-text). Pull both with ollama pull llama3.2 nomic-embed-text.

DEVLOG_INTERACTIVE_FORCE

Set to 1 to bypass the TTY check that normally gates devlog --interactive. Useful in tests, scripts, or remote shells. The check still applies to devlog edit <id> with no flags unless DEVLOG_ALLOW_EDITOR_IN_PIPE=1 is also set.

DEVLOG_ALLOW_EDITOR_IN_PIPE

Set to 1 to allow devlog edit <id> with no flags to spawn $EDITOR even when stdin is not a TTY. The default is to error out, since editors like nano/vi print screen-clear sequences that pollute captured output. Set this when scripting edits via the editor.

Themes

devlog's colors are themable. A user theme lives at ~/.devlog/theme.toml (or $DEVLOG_DATA_DIR/theme.toml when set) and overrides individual color roles. Roles you omit use the built-in defaults, so the file is always optional.

# See the path to your active theme file
devlog theme path
# → /Users/you/.devlog/theme.toml

# See every role and its current value
devlog theme list

# See a single role
devlog theme show date
# → cyan

# Dump a starter theme.toml to STDOUT (all roles commented out, safe template)
devlog theme show > my-theme.toml

# Install a theme file
devlog theme set ~/dotfiles/devlog-theme.toml
# → Theme installed at /Users/you/.devlog/theme.toml (17 roles).

The file format is standard TOML with one [palette] section. Each key is a role (the UI element to color) and each value is a Rich style string — a named color, a hex code, a 256-color index, or a composite like "bold yellow".

# ~/.devlog/theme.toml
[palette]
date             = "bright_cyan"   # default: "cyan"
tags             = "white"         # default: "magenta"
success_border   = "bright_green"  # default: "green"
match_highlight  = "bold magenta"  # default: "bold yellow"
id_dim           = "grey50"        # default: "dim white"

The full list of roles:

RoleUsed forDefault
error_borderred panel border on errorsred
error_textred error text and ✘ iconred
warning_textyellow warning text and ⚠ iconyellow
info_textdim ℹ info linedim
success_bordergreen border on add success panelgreen
success_textgreen body text on ✔ confirmation linesgreen
success_titlegreen title + ✔ icon on add successbold green
show_bordercyan border on show and stats panelscyan
delete_borderred border + ✘ on deletered
edit_borderblue border + ✎ on editblue
datecyan date cells in tables and panelscyan
updatedyellow "Updated" cellsyellow
tagsmagenta tag cellsmagenta
id_dimdim short-id cellsdim white
match_highlightyellow search-match highlightbold yellow
banner_versionversion number on --versionbold cyan
banner_commandcommand names in root help bannerbold cyan
prompt_borderinteractive REPL promptmagenta
table_captiondim caption under a tabledim
table_footerbold footer under a tablebold
sparkline30-day histogram in statscyan
zebra_altalternate-row dim style in listdim
heatmap_basebase hue for the calendar heatmapgreen
heatmap_emptyempty cells in the calendar heatmapgrey15
heatmap_l1lightest non-zero tier in the heatmapgreen
heatmap_l2second heatmap tiercolor(34)
heatmap_l3third heatmap tiercolor(40)
heatmap_l4busiest day in the heatmapcolor(46)

Notes:

  • Box styles, icons, and layout are not themable in this version. The theming layer is intentionally limited to colors.
  • A malformed theme.toml is non-fatal: devlog prints one warning to STDERR (Warning: theme file at … is invalid; using default theme.) and renders with the defaults.
  • Unknown role keys are dropped with a warning per key.
  • NO_COLOR=1 and non-TTY output always suppress color regardless of the theme.
  • Changes take effect on the next devlog invocation; no daemon or reload needed.

Development Setup

# 1. Clone the repository
git clone https://github.com/SpIob/devlog-cli.git
cd devlog-cli

# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install in editable mode with development dependencies
pip install -e .
pip install pytest

# 4. Verify the installation
devlog --version

# 5. Run the test suite
pytest

Project layout:

devlog-cli/
├── devlog/
│   ├── __init__.py         ← package metadata (__version__)
│   ├── cli/                ← Click entry point, split by command group
│   │   ├── __init__.py     ← root group; registers every group below
│   │   ├── _shared.py      ← load/exit glue, validation, doctor plumbing
│   │   ├── entries.py      ← add / show / edit / delete / list / search
│   │   ├── views.py        ← today / yesterday / week / on / tail / calendar
│   │   ├── tags.py         ← tags / tag / merge-tag / rename-tag
│   │   ├── stats.py        ← stats
│   │   ├── transfer.py     ← import / export
│   │   ├── maintenance.py  ← repair / backup / restore / undo / doctor
│   │   └── meta.py         ← completions
│   ├── _commands.py        ← Single source of truth for command list
│   ├── ui/                 ← Rich rendering helpers (panels, tables, errors)
│   │   ├── __init__.py     ← facade; owns the real consoles
│   │   ├── _base.py        ← layout constants, styles, console proxies
│   │   ├── text.py         ← plurals, truncation, error/info lines
│   │   ├── layout.py       ← terminal-width arithmetic and tables
│   │   ├── panels.py       ← per-entry and summary panels
│   │   ├── calendar.py     ← activity heatmap (sparkline, month grid)
│   │   ├── banner.py       ← version / root banners
│   │   └── progress.py     ← export progress bar
│   ├── themes.py           ← Theme loader, role contract, palette helpers
│   ├── theme_preview.py    ← Synthetic UI fixture for theme create previews
│   ├── storage/            ← Storage facade (dispatch by DEVLOG_BACKEND)
│   │   ├── __init__.py     ← facade: public API + backend dispatch
│   │   ├── _base.py        ← exceptions, paths, locking, validation, stats
│   │   ├── _json.py        ← default backend (entries.json, atomic writes)
│   │   └── _sqlite.py      ← opt-in backend (entries.db, WAL)
│   ├── models.py           ← Entry dataclass / TypedDict definition
│   ├── _completions.py     ← Bash / zsh / fish completion script generators
│   ├── _dates.py           ← Date-range parsing, week boundaries, TZ helpers
│   ├── _filter.py          ← Shared filter chain (tag → date → sort)
│   ├── _interactive.py     ← Line-based REPL dispatcher
│   ├── _io.py              ← Export/import readers and writers
│   ├── _iso.py             ← ISO-8601 parsing / formatting helpers
│   ├── _time.py            ← UTC timestamps + timezone resolution helpers
│   ├── _tagops.py          ← Tag normalisation, validation, merge helpers
│   ├── _git_cli.py         ← `devlog git` command group (status/sync/log)
│   ├── _gitops.py          ← Git plumbing for the git command group
│   ├── _aiops.py           ← Pure AI core: extractive digest, cosine ranking, answer formatting
│   ├── _ollama.py          ← Minimal stdlib Ollama HTTP client (generate/embed)
│   ├── _aiindex.py         ← Embedding index for `ask` (build/reuse/prune, embeddings.json)
│   ├── _ai_cli.py          ← `devlog digest` and `devlog ask` commands
│   ├── _mcp_server.py      ← MCP protocol + journal tools (stdlib JSON-RPC over stdio)
│   ├── _mcp_cli.py         ← `devlog mcp` command
│   └── builtins/           ← Bundled theme files (default, dracula, nord, …)
│       ├── __init__.py
│       ├── default.toml
│       ├── dracula.toml
│       ├── gruvbox.toml
│       ├── high_contrast.toml
│       ├── monokai.toml
│       ├── nord.toml
│       ├── one_dark.toml
│       └── solarized.toml
├── tests/
│   ├── conftest.py
│   ├── test_add.py
│   ├── test_ai_cli.py
│   ├── test_aiindex.py
│   ├── test_aiops.py
│   ├── test_backup_restore.py
│   ├── test_calendar.py
│   ├── test_completions.py
│   ├── test_date_range.py
│   ├── test_delete.py
│   ├── test_doctor.py
│   ├── test_edit.py
│   ├── test_export.py
│   ├── test_git_features.py
│   ├── test_import.py
│   ├── test_importers.py
│   ├── test_interactive.py
│   ├── test_limit_validation.py
│   ├── test_list.py
│   ├── test_merge_tag.py
│   ├── test_mcp_server.py
│   ├── test_models.py
│   ├── test_ollama.py
│   ├── test_performance.py
│   ├── test_rename_tag.py
│   ├── test_repair.py
│   ├── test_search.py
│   ├── test_show.py
│   ├── test_sqlite_backend.py
│   ├── test_stats_v2.py
│   ├── test_tag_command.py
│   ├── test_tags.py
│   ├── test_theme_create_bugs.py
│   ├── test_themes.py
│   ├── test_timezone.py
│   ├── test_today_tail_stats.py
│   ├── test_ui_columns.py
│   ├── test_ui.py
│   └── test_undo.py
├── pyproject.toml
└── README.md

Tests use Click's CliRunner for full end-to-end command testing without touching the real filesystem. Each command has a happy-path test, an empty-state test, and at least one error-condition test.


License

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

PYPI
devlog-tool
Install Command
pip install devlog-tool