devlog-cli
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
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.
| devlog | jrnl | Day One | plain 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
MESSAGE |
— | string | Yes | — | The body of the journal entry. |
--tag |
-t |
string | No | — | Attach a tag to the entry. Repeatable: -t backend -t bugfix. Tags are normalized to lowercase. Allowed characters: [a-z0-9-]. |
--at |
— | string | No | — | 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 |
-q |
flag | No | False | Suppress 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--tag |
-t |
string | None | Filter by tag. Repeatable. Multiple flags use AND logic — entry must carry all specified tags. |
--limit |
-n |
integer | 20 | Maximum number of entries to display. Must be a positive integer. |
--all |
— | flag | False | Override --limit and display every entry. |
--since |
— | string | None | Only show entries on or after this date. See Date filters. |
--until |
— | string | None | Only show entries on or before this date. See Date filters. |
--quiet |
-q |
flag | False | Output 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
QUERY |
— | string | Yes | — | 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 |
-t |
string | No | None | Narrow results to entries that also carry these tags. Repeatable; AND logic. |
--limit |
-n |
integer | No | 20 | Maximum number of results to display. |
--since |
— | string | No | None | Only show entries on or after this date. See Date filters. |
--until |
— | string | No | None | Only show entries on or before this date. See Date filters. |
--regex |
— | flag | No | False | Interpret QUERY as a case-insensitive regular expression. Invalid patterns exit with code 2. |
--quiet |
-q |
flag | No | False | Output 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
QUERYis rejected withQUERY 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
DATE |
— | string | Yes | — | today, yesterday, Nd (N days ago, e.g. 3d), or an absolute YYYY-MM-DD. |
--limit |
-n |
integer | No | 50 | Maximum entries to show. |
--quiet |
-q |
flag | No | False | Output raw JSON lines. |
Notes:
- The day bucket is the local date when
DEVLOG_TZis set, otherwise UTC — same rule astoday/yesterday/week. - An unparseable
DATEexits 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
ID |
— | string | Yes | — | The 8-char short id, the full UUID, or a unique prefix of either. |
--quiet |
-q |
flag | No | False | Output 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).
Updateddisplays—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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
ID |
— | string | Yes | — | The 8-char short id, the full UUID, or a unique prefix. |
--message |
-m |
string | No | — | Replace the message text. |
--tag |
-t |
string, repeatable | No | — | Replace the tag set with this list. Existing tags are discarded. |
--add-tag |
— | string, repeatable | No | — | Append tags to the existing set. Duplicates are silently dropped. |
--remove-tag |
— | string, repeatable | No | — | Remove tags from the existing set. |
--at |
— | string | No | — | Replace the entry's created_at. Same format as add --at. Prompts for confirmation unless --yes is also passed. |
--yes |
-y |
flag | No | False | Skip the --at confirmation prompt. |
--quiet |
-q |
flag | No | False | Suppress confirmation output. |
Notes:
- If no flag is passed, the entry's current message is opened in
$VISUAL/$EDITOR(falling back tonanoorviif 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),editwith no flags errors out instead of dumping terminal escapes. SetDEVLOG_ALLOW_EDITOR_IN_PIPE=1to opt in to the old behaviour. - An empty
--messageis rejected with the sameMESSAGE cannot be emptyerror asdevlog 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:
--tagruns first, then--add-tagadds, then--remove-tagremoves. - 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
ID |
— | string | Yes | — | The 8-char short id, the full UUID, or a unique prefix. |
--yes |
-y |
flag | No | False | Skip the confirmation prompt. |
--quiet |
-q |
flag | No | False | Suppress the success panel. |
--ignore-missing |
— | flag | No | False | Exit 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--sort |
— | choice | count |
One of count (most-used first), name (alphabetical), or recent (most recently used first). |
--limit |
-n |
integer | 50 | Maximum number of tags to show. |
--all |
— | flag | False | Override --limit and show every tag. |
--quiet |
-q |
flag | False | Output {tag, count, last_used} JSON lines instead of the table. |
Notes:
Last usedis the more recent of the entry'screated_atandupdated_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
| Subcommand | Description |
|---|---|
devlog theme list |
Print 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 PATH |
Validate 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 NAME |
Install 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 builtins |
List all bundled theme names with their short description. |
devlog theme reset |
Remove the active theme file and fall back to the defaults. Prompts for confirmation. |
devlog theme edit |
Open the active theme file in $VISUAL/$EDITOR. Creates a starter template if no file exists yet. |
devlog theme create |
Interactively walk through every role, preview the palette, and install it as the active theme (or write to --output PATH). |
devlog theme diff |
Show the active theme's overrides relative to the built-in defaults. With --default, inverts to show roles that still match the defaults. |
devlog theme export |
Write the active palette as a complete, uncommented theme.toml to --output PATH or --stdout. |
devlog theme path |
Print the absolute path to the active theme file. |
Notes:
theme listaccepts--flat(disable section grouping) and--no-preview(hide the preview swatch column).theme setaccepts--checkto validate a theme file without installing it (exits 1 on any error).theme createaccepts--from BUNDLED_NAMEto seed values from a built-in theme,--name/--descriptionfor[meta],--output PATHto write to a file instead of installing, and--install/--no-installto control installation explicitly.theme exportrequires exactly one of--stdoutor--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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--limit |
-n |
integer | 50 | Maximum entries to show. |
--quiet |
-q |
flag | False | Output raw JSON lines instead of a table. |
Notes:
- "Today" is computed in the local zone when
DEVLOG_TZis set, otherwise UTC. SetDEVLOG_TZ=America/New_Yorkto maketoday,yesterday, andweekreflect 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--limit |
-n |
integer | 50 | Maximum entries to show. |
--quiet |
-q |
flag | False | Output 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--limit |
-n |
integer | 100 | Maximum entries to show. |
--day |
— | string (YYYY-MM-DD) | today | Anchor day; the week ends on this day and includes the 6 days before it. |
--quiet |
-q |
flag | False | Output 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 / Option | Short | Type | Default | Description |
|---|---|---|---|---|
N |
— | integer | 5 | Number of entries to show. |
--tag |
-t |
string, repeatable | None | Filter by tag (AND logic). |
--quiet |
-q |
flag | False | Output 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--quiet |
-q |
flag | False | Output a single JSON object with the summary. |
--since |
— | string | None | Only include entries on or after this date. See Date filters. |
--until |
— | string | None | Only 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 whenDEVLOG_TZis set, otherwise UTC. - The
First/Last/Spanlines render in the local zone whenDEVLOG_TZis set (the… UTCsuffix becomes the zone's key, e.g.… EST). - The
Streakline 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 agois the nudge line. Top tag pairslists the tag co-occurrences — the two tags most often written on the same entry.--quietaddsstreaks({"current": N, "longest": N}),top_tag_pairs([{"tags": [a, b], "count": N}]), anddays_since_lastto 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
NAME |
— | string | Yes | — | The tag to inspect. Normalised to lowercase. |
--delete |
— | flag | False | Strip the tag from every entry that has it (prompts for confirmation; use -y to skip). |
|
--yes |
-y |
flag | False | With --delete: skip the confirmation prompt. |
|
--dry-run |
— | flag | False | With --delete: show what would change without writing. |
|
--limit |
-n |
integer | 20 | Show mode: max entries to list. | |
--all |
— | flag | False | Show mode: override --limit and list every entry. |
|
--quiet |
-q |
flag | False | Output raw JSON lines (or suppress the success line under --delete). |
Notes:
NAMEis validated with the same rules asdevlog add— see Tag rules.devlog tag NAME --deleteasksRemove tag "NAME" from N entries?by default — pass-y/--yesto skip, or combine with--quietto skip the prompt in scripts.devlog tag NAME --delete --dry-runpreviews the change without writing.- Use
devlog merge-tag A Bif 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--year |
— | integer | current year | Year to render. |
--quiet |
-q |
flag | False | Output a {YYYY-MM-DD: count} JSON map for the year. |
Notes:
- The grid uses the
heatmap_empty/heatmap_l1…heatmap_l4theme roles. See Themes to restyle. - The bucketing date is the local date when
DEVLOG_TZis set, otherwise UTC. WithDEVLOG_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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
OLD |
— | string | Yes | — | The existing tag to replace. |
NEW |
— | string | Yes | — | The new tag name. Validated as a tag (see Tag rules). |
--dry-run |
— | flag | No | False | Show the count of affected entries without writing. |
--quiet |
-q |
flag | No | False | Suppress the success line. |
Notes:
- Every entry that contains
OLDis rewritten in place. The entry'screated_atis preserved andupdated_atis 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, printsNo entries with tag "<old>".and exits 0. NEWis 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
OLD |
— | string | Yes | — | The tag to retire. |
NEW |
— | string | Yes | — | The tag to consolidate into. Validated as a tag (see Tag rules). |
--dry-run |
— | flag | False | Show the count of affected entries without writing. | |
--quiet |
-q |
flag | False | Suppress the success line. |
Notes:
- If
OLD.lower() == NEW.lower()after normalisation, the command printsOLD and NEW are the same ("…"). No changes made.and exits 0. - If no entries carry
OLD, printsNo entries with tag "OLD".and exits 0. - For a pure rename use
devlog rename-tag. For stripping a tag entirely, usedevlog 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
PATH |
— | path | Yes | — | Input file. Must exist and be readable. |
--format |
-f |
choice | auto |
One of auto, json, markdown, jrnl, dayone. auto picks by file extension, then by content sniffing. |
|
--dry-run |
— | flag | False | Show what would be imported without writing. | |
--quiet |
-q |
flag | False | Suppress 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
idvalues in the source JSON are preserved across re-imports, so adevlog export→devlog importround-trip keeps short ids stable for cross-referencing. If the source row omitsid, 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
entriesarray whose items carrytext/date/starred.textbecomes the message,date(naive timestamps are treated as UTC) becomescreated_at,tagscarry over, and a starred entry gains astarredtag. Re-imports dedupe by fingerprint since jrnl rows have no stable ids. - Day One format: an object with an
entriesarray whose items carrycreationDate/text. The Day Oneuuidis preserved as the entry id; tags are lowercased with spaces converted to hyphens. - If the file format cannot be detected and
--formatwas 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]
| Command | Option | Type | Default | Description |
|---|---|---|---|---|
git status |
--json |
flag | False | Emit the full status (repo root, branch, remote, clean flag, changed files) as one JSON object. |
git sync |
--message / -m |
string | devlog: journal update |
Commit message used when changes are found. |
git sync |
--quiet / -q |
flag | False | Suppress output. |
git log |
--oneline |
flag | False | One commit per line. |
git log |
--limit / -n |
integer | 20 | Maximum commits to show. |
Notes:
- Commands resolve the repository containing your data dir (
DEVLOG_DATA_DIRor~/.devlog) — the data dir itself does not need to be the repo root; a journal subdirectory inside a repo works. git statusreportsis_git_repo: false(exit 0) when no repository is found.git syncrunsgit add -A+git commitonly whengit status --porcelainis non-empty; a clean repo is a no-op. Exits 1 when the data dir is not inside a repository.git logprints the repository's commit log (not filtered to journal files). A repository with no commits exits 1 with git'sdoes not have any commits yeterror.
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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
NOTE |
— | string | Yes* | — | 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 | — | None | Any ref git show accepts: HEAD, HEAD~1, a sha, a branch name. |
--tag / -t |
— | string | No | None | Extra tags, merged in front of the ones extracted from the commit. |
--at |
— | timestamp | No | author date | Override 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 tagauth/api; a[tag]message prefix also becomes a tag; acommit-<short-hash>tag is always added for cross-referencing back togit 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):
| Command | What 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. |
today |
Show today's entries. |
y | yesterday |
Show yesterday's entries. |
w | week |
Show the current week. |
tail [N] |
Show the N most recent entries. |
tags |
List tags with usage counts. |
stats |
Summarize 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. |
calendar |
Year-grid heatmap of journal activity. |
theme |
View 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. |
doctor |
Check store health. |
h | help |
Show the REPL help. |
q | quit | exit |
Leave the REPL. |
Notes:
- Requires a TTY. Outside a TTY the command exits with code 1 and a clear error message. Set
DEVLOG_INTERACTIVE_FORCE=1to 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--output |
-o |
path | <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 |
-f |
auto | markdown | json |
auto |
Output format. auto infers from the --output extension (.json → JSON, .md/.markdown → Markdown, anything else → Markdown). Explicit --format wins over the extension. |
--tag |
-t |
string | None | Export only entries that carry all specified tags. Repeatable; AND logic. |
--since |
— | string | None | Only export entries on or after this date. See Date filters. |
--until |
— | string | None | Only export entries on or before this date. See Date filters. |
--quiet |
-q |
flag | False | Suppress 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--dry-run |
— | flag | False | Show the issues and what would be dropped, without writing. |
--yes |
-y |
flag | False | Skip the "drop N entries — continue?" confirmation. |
--backup / --no-backup |
— | flag | --backup |
Write a timestamped backup to <data-dir>/backups/ before the rewrite. |
--quiet |
-q |
flag | False | Suppress 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
idandmessage, a parseablecreated_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
0when nothing was dropped,1when 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--output |
-o |
path | <data-dir>/backups/entries-TIMESTAMP.json |
Backup file path. Parent directories are created if they don't exist. |
--quiet |
-q |
flag | False | Print only the backup path (no success panel). |
Notes:
- The backup is just a copy of
entries.json(the JSON shape thatdevlogreads on every startup). It can be inspected, edited, and used as input todevlog 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--yes |
-y |
flag | False | Skip the confirmation prompt. |
--keep |
— | int | 10 | Pre-write snapshots to retain after pruning (0 removes all). |
--dry-run |
— | flag | False | Show what would be restored, without writing. |
--quiet |
-q |
flag | False | Suppress the summary output. |
Notes:
- Repeated
undocalls 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 backupfiles are never touched or consumed. - To redo after an undo, restore a manual backup: run
devlog backupbefore experimenting, thendevlog 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 / Option | Short | Type | Required | Default | Description |
|---|---|---|---|---|---|
PATH |
— | path | Yes | — | Backup file. Must exist and be readable. |
--yes |
-y |
flag | No | False | Skip the "overwrite current journal?" confirmation. |
--dry-run |
— | flag | No | False | Validate the backup and report what would be restored, without writing. |
--quiet |
-q |
flag | No | False | Suppress the success line. |
Notes:
- A non-empty journal prompts for confirmation by default; pass
-yto skip the prompt in scripts. - If the backup is structurally invalid (root is not a JSON object, or
entriesis 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-runfirst 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--quiet |
-q |
flag | False | Output a single JSON object with the report. |
Notes:
- Exit code:
0when the store is clean,1when validation issues are found (rundevlog repairto fix),2when 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--week |
— | flag | True | Summarize the last 7 days (the only period in this release). |
--day |
— | string | today | Anchor day (YYYY-MM-DD); the week ends on this day and spans the 6 before it. |
--llm |
— | flag | False | Also produce an LLM-written summary via local Ollama. |
--model |
— | string | llama3.2 |
Ollama model for --llm. |
--quiet |
-q |
flag | False | Print the digest text only (no header). |
--json |
— | flag | False | Output 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(orDEVLOG_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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--top |
-n |
int | 5 | Max matches to show. |
--json |
— | flag | False | Output {"query", "results": [{id, message, created_at, score}, …]} sorted by descending score. |
--model |
— | string | nomic-embed-text |
Embedding 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
jsonandsqlitebackends. - 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]
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--check |
— | flag | False | Print 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
Backendis stored asbackend. 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.
| Format | Meaning |
|---|---|
YYYY-MM-DD |
That date at 00:00 UTC. As an upper bound, includes the whole day. |
YYYY-MM-DDTHH:MM |
ISO 8601, treated as UTC if no offset. |
YYYY-MM-DDTHH:MM:SSZ |
ISO 8601 with explicit UTC. |
YYYY-MM-DD HH:MM |
Space-separated form, same semantics as T. |
today |
Today at 00:00 UTC. |
yesterday |
Yesterday at 00:00 UTC. |
Nd |
N days ago at 00:00 UTC (e.g. 7d, 30d). |
Nw |
N 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 pattern | Full-file rewrite (atomic tmp + os.replace) |
Single-row INSERT/UPDATE/DELETE in a transaction |
| Concurrency | Cross-process flock/msvcrt locking |
WAL journal mode + 5s busy timeout |
| Sweet spot | Journals up to ~10k entries | 10k+ entries, multiple simultaneous processes |
| Corrupt-file recovery | repair right-truncation recovery |
Not 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.
backupalways writes a JSON snapshot regardless of backend, sobackup→ switch backend →restoremigrates 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
doctorandrepairare 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, andcalendarbucket entries by local date.--since/--untilandNd/Nware interpreted at local midnight and converted to UTC for the comparison.statsrenders theFirst/Last/Spanlines with the zone's key suffix (e.g.… EST) instead of… UTC.add --at "2025-08-28 09:00"andedit --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.
| Variable | Default | Purpose |
|---|---|---|
DEVLOG_AI |
unset | Set to 1 to make digest --week produce an LLM summary by default (same as passing --llm each time). |
DEVLOG_OLLAMA_HOST |
http://127.0.0.1:11434 |
Ollama server URL — point it at another machine on your LAN (e.g. http://odysseus:11434) if the model does not run locally. |
DEVLOG_EMBED_MODEL |
nomic-embed-text |
Embedding 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:
| Role | Used for | Default |
|---|---|---|
error_border |
red panel border on errors | red |
error_text |
red error text and ✘ icon | red |
warning_text |
yellow warning text and ⚠ icon | yellow |
info_text |
dim ℹ info line | dim |
success_border |
green border on add success panel |
green |
success_text |
green body text on ✔ confirmation lines | green |
success_title |
green title + ✔ icon on add success |
bold green |
show_border |
cyan border on show and stats panels |
cyan |
delete_border |
red border + ✘ on delete |
red |
edit_border |
blue border + ✎ on edit |
blue |
date |
cyan date cells in tables and panels | cyan |
updated |
yellow "Updated" cells | yellow |
tags |
magenta tag cells | magenta |
id_dim |
dim short-id cells | dim white |
match_highlight |
yellow search-match highlight | bold yellow |
banner_version |
version number on --version |
bold cyan |
banner_command |
command names in root help banner | bold cyan |
prompt_border |
interactive REPL prompt | magenta |
table_caption |
dim caption under a table | dim |
table_footer |
bold footer under a table | bold |
sparkline |
30-day histogram in stats |
cyan |
zebra_alt |
alternate-row dim style in list |
dim |
heatmap_base |
base hue for the calendar heatmap | green |
heatmap_empty |
empty cells in the calendar heatmap |
grey15 |
heatmap_l1 |
lightest non-zero tier in the heatmap | green |
heatmap_l2 |
second heatmap tier | color(34) |
heatmap_l3 |
third heatmap tier | color(40) |
heatmap_l4 |
busiest day in the heatmap | color(46) |
Notes:
- Box styles, icons, and layout are not themable in this version. The theming layer is intentionally limited to colors.
- A malformed
theme.tomlis 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=1and 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.
Metadata
Release files for devlog-tool 2.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| devlog_tool-2.0.1.tar.gz | 278.8 kB | With provenance | Details for devlog_tool-2.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| devlog_tool-2.0.1-py3-none-any.whl | Python 3 | none | any | Details for devlog_tool-2.0.1-py3-none-any.whl |
Total release size: 447.6 kB
Release files / devlog_tool-2.0.1.tar.gz
| Download URL | devlog_tool-2.0.1.tar.gz |
|---|---|
| Size | 278.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0e60a6f8b30e72df4218e88cbbe923c1865a11f615d4f92f2f9b8d8d2f98605c
|
|
BLAKE2b-256 checksum How to use checksums |
d7edc383b1de2936b7b298b4cd10ffd93ff875a8a8ea4f168e7a80c67ed5a1b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / devlog_tool-2.0.1-py3-none-any.whl
| Download URL | devlog_tool-2.0.1-py3-none-any.whl |
|---|---|
| Size | 168.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7ee094ac2bbc2fec4347859c4811c96d31acdefc49c88e64c6cae7faace6b767
|
|
BLAKE2b-256 checksum How to use checksums |
d855fdbee66d99287f7df16a764c9436e681f03449269a10575d94f3b37d056b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for devlog-tool 2.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for devlog_tool-2.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.