apple-journal-cli 1.0.5 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # journal-cli
1
+ # apple-journal-cli
2
2
 
3
3
  **Read and write Apple Journal entries from the terminal.** Text, photos,
4
4
  videos, Live Photos, web links, location pins, bookmarks, multiple journals —
@@ -18,9 +18,21 @@ $ journal-cli list --limit 3
18
18
 
19
19
  $ journal-cli show 117
20
20
  audio (asset 705) 2.2s "This is a test of an audio recording."
21
- location 15835 NE 36th St, Redmond (47.641544, -122.129299)
21
+ location Golden Gate Bridge, San Francisco (37.8199, -122.4783)
22
22
  ```
23
23
 
24
+ > [!WARNING]
25
+ > **Back up your journal first.** journal-cli writes directly to Apple
26
+ > Journal's private, undocumented data store. Apple does not support this; a
27
+ > macOS update can change the schema at any time, and a bad write could
28
+ > corrupt entries or confuse iCloud sync across **all** your devices. Before
29
+ > your first live write, export a backup in Journal.app (**Journal → Settings
30
+ > → Export Journal Entries…**). journal-cli also snapshots the local store to
31
+ > `~/Backups/journal-cli/` before every live write, but that cannot undo
32
+ > anything that has already synced to iCloud. **Use at your own risk.** The
33
+ > CLI requires a one-time risk acknowledgment before its first live write
34
+ > (interactive prompt, or `--accept-risk`).
35
+
24
36
  ## Install
25
37
 
26
38
  ```sh
@@ -48,7 +60,7 @@ Journal.app is open and never lock the live database.
48
60
  journal-cli list --limit 20 --full # --full prints bodies
49
61
  journal-cli list --since 2025-01-01 --until 2025-12-31
50
62
  journal-cli show 95 # entry + assets + attachment paths
51
- journal-cli search anguilla
63
+ journal-cli search tokyo
52
64
  journal-cli export --dir ~/journal-export # one .md per entry, YAML frontmatter
53
65
  journal-cli export --dir ~/export --format json
54
66
  journal-cli stats # counts, words, by-year histogram
@@ -64,8 +76,11 @@ text from drawings.
64
76
  ## Writing
65
77
 
66
78
  Writes against the real store require `--live`, refuse to run while
67
- Journal.app is open, and take a timestamped backup to `~/Backups/journal-cli/`
68
- first. New entries sync to iCloud like native ones — verified end to end,
79
+ Journal.app is open, take a timestamped backup to `~/Backups/journal-cli/`
80
+ first, and require a **one-time risk acknowledgment** (interactive prompt, or
81
+ `--accept-risk` for scripts — agents should ask their user before passing it).
82
+ Every mutating command also takes `--dry-run`, which prints the plan and
83
+ writes nothing. New entries sync to iCloud like native ones — verified end to end,
69
84
  including CloudKit accepting attached files.
70
85
 
71
86
  ```sh
@@ -86,8 +101,14 @@ journal-cli write --live --body "At the office" \
86
101
  # web link (renders as a rich link card)
87
102
  journal-cli write --live --body "Read this" --link https://example.com --link-title "A Post"
88
103
 
89
- # target a journal; link photos back to the Photos library
104
+ # markdown -> Journal's own rich text (bold, italic, lists, strikethrough)
105
+ journal-cli write --live --markdown --body-file entry.md
106
+
107
+ # stage in a Mac-local journal; link photos back to the Photos library
90
108
  journal-cli write --live --journal "Travel" --body "..." --media IMG_0079.JPG --photos-link
109
+
110
+ # audit staged memberships and print the native Journal.app finalization steps
111
+ journal-cli sync-journals --journal "Travel"
91
112
  ```
92
113
 
93
114
  ### Editing
@@ -98,7 +119,7 @@ journal-cli edit 103 --live --lat 47.6 --lon -122.3 --place Home # set/replace
98
119
  journal-cli edit 103 --live --add-media c.heic --add-link https://example.org
99
120
  journal-cli edit 103 --live --remove-media 700 # ids shown by `show`
100
121
  journal-cli edit 103 --live --clear-location --no-bookmark
101
- journal-cli edit 103 --live --journal "Travel" # move journals
122
+ journal-cli edit 103 --live --journal "Travel" # stage an imported entry
102
123
  ```
103
124
 
104
125
  ### Deleting
@@ -110,6 +131,43 @@ journal-cli empty --live # purge never-synced deleted entries
110
131
  journal-cli delete 103 --live --hard # full row+file removal (guarded, see below)
111
132
  ```
112
133
 
134
+ ## Coming from Day One?
135
+
136
+ `skills/dayone-import/` migrates Day One journals into Apple Journal, entry
137
+ by entry, with photos, locations, titles and bookmarks intact.
138
+
139
+ ```sh
140
+ S=skills/dayone-import/scripts/dayone-import.py
141
+
142
+ python3 $S journals # list Day One journals
143
+ python3 $S plan "Travel Journal" # what imports, and what can't
144
+ python3 $S import "Travel Journal" --into "Travel" --target-db "$(journal-cli sandbox --dir /tmp/r)"
145
+ python3 $S import "Travel Journal" --into "Travel"
146
+ ```
147
+
148
+ It reads Day One's own SQLite store rather than its markdown export, because
149
+ the export **renders every timestamp in the exporting machine's timezone**.
150
+ Entries written abroad come out hours off and some land on the wrong day. The
151
+ original zone is in the store, so the import can preserve the wall clock you
152
+ actually experienced. `fix-export` repairs an export you already have.
153
+
154
+ Two more things it knows:
155
+
156
+ - **Day One's location is where the *app* was**, not where the photos were
157
+ taken — entries written up later carry your home address. `fix-locations`
158
+ corrects them from photo EXIF, corroborated against the Photos library so a
159
+ camera with a stale GPS fix can't drag a whole trip to one spot.
160
+ - **Day One keeps media cloud-only** until asked. A journal can look complete
161
+ in the app while almost nothing is on disk. `plan` reports the shortfall
162
+ before you import anything.
163
+ - **Day One writes Markdown, Journal renders rich text.** Entries are
164
+ converted with `--markdown`, so headings become bold, `- ` and `1. ` become
165
+ real lists, and Day One's `\.` escaping disappears instead of showing up
166
+ literally. `fix-text` re-renders entries imported before this existed.
167
+
168
+ Imports are resumable, keyed by Day One's entry UUIDs, so re-running never
169
+ double-writes.
170
+
113
171
  ## Agent-friendly by design
114
172
 
115
173
  journal-cli is built to be driven by AI agents and scripts as much as by
@@ -128,15 +186,17 @@ humans:
128
186
  hands back a disposable copy of the store; every other command accepts
129
187
  `--db` (or `$JOURNAL_DB`) to target it. Agents can rehearse a write with
130
188
  zero risk, then replay it `--live`.
131
- - **A skill ships in-repo** — `skills/journal-cli/SKILL.md` teaches
189
+ - **Skills ship in-repo** — `skills/journal-cli/SKILL.md` teaches
132
190
  Claude-style agents the command surface, the safety model, and the sharp
133
- edges.
191
+ edges; `skills/dayone-import/SKILL.md` covers migrating from Day One.
134
192
 
135
193
  ## Safety model
136
194
 
137
195
  | Layer | Behavior |
138
196
  |---|---|
139
197
  | Reads | temp snapshot of `db`+`-wal`+`-shm`; live store never opened for read |
198
+ | Risk acknowledgment | first live write requires typing "I understand" (or `--accept-risk`); stored in `~/.config/journal-cli/` |
199
+ | `--dry-run` | every mutating command can print its plan and write nothing |
140
200
  | `--live` gate | writes to the real store refuse to run without it |
141
201
  | App check | writes refuse to run while Journal.app is open |
142
202
  | Auto-backup | every live write snapshots the store to `~/Backups/journal-cli/` first |
@@ -153,14 +213,14 @@ engine uploads them all to CloudKit — including the attachment files — and a
153
213
  delete/restore round trip propagates. The read pipeline has been swept over an
154
214
  entire real store: every entry row and all ~700 asset metadata blobs parse.
155
215
 
156
- The test suite (`tests/test_write.sh`, 110 assertions) runs the whole command
216
+ The test suite (`tests/test_write.sh`) runs the whole command
157
217
  surface against a disposable copy of a store — argument guards, insert
158
218
  bookkeeping, RTF round-trips, location metadata, media file layout, Live Photo
159
219
  pairing, Photos linkage, journal targeting, link assets, the delete/restore
160
220
  lifecycle, and `PRAGMA integrity_check`. Point `JOURNAL_SEED` at a backup to
161
221
  run it without Full Disk Access. `JOURNAL_CLI` selects the binary under test;
162
- the Python reference implementation in `reference/` passes the identical
163
- suite.
222
+ the Python implementation in `reference/` remains an executable reference for
223
+ the original command surface.
164
224
 
165
225
  ## How it works
166
226
 
@@ -183,7 +243,7 @@ the sync cache.)
183
243
  | asset metadata | one version byte `0x01` + JSON; `0x02` + UUID = Core Data external storage in `.moments_SUPPORT/_EXTERNAL_DATA/` |
184
244
  | links | base64 `NSKeyedArchiver`-archived `LPLinkMetadata` inside the asset metadata |
185
245
  | audio | asset metadata carries duration, waveform, and a word-level transcript |
186
- | journals | `ZJOURNALMO` (names live in each journal's CRDT blob) + `Z_5JOURNALS` join |
246
+ | journals | `ZJOURNALMO` (names live in each journal's merge blob) + `Z_5JOURNALS` join; direct join changes are Mac-local until Journal.app performs a native move and authors the per-entry merge data |
187
247
  | new-row bookkeeping | fresh `Z_PK`, bumped `Z_PRIMARYKEY.Z_MAX`, 16-byte UUID `ZID`, `ZISUPLOADEDTOCLOUD=0` — Journal's sync engine adopts the row and uploads it |
188
248
 
189
249
  ### The CRDT limitation
@@ -201,8 +261,8 @@ entry whose text was typed in the app. Consequences:
201
261
  - **`edit` refuses to rewrite text on CRDT-bearing entries** unless `--force`
202
262
  is passed: rewriting only the RTF leaves the CRDT holding the old text with
203
263
  authoritative history, and sync can revert or duplicate the edit. Location,
204
- media, links, date, bookmark and journal moves are safe on any entry — none
205
- of that state lives in the CRDT (verified across a real library).
264
+ media, links, date, and bookmark remain editable. Journal moves on entries
265
+ with merge data must be performed in Journal.app so they sync correctly.
206
266
  - **CLI-written entries have no CRDT.** Journal renders and syncs them fine,
207
267
  but a simultaneous edit on two devices may not merge like an app-authored
208
268
  entry would.
package/bin/journal-cli CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apple-journal-cli",
3
- "version": "1.0.5",
3
+ "version": "1.1.0",
4
4
  "description": "Read and write Apple Journal entries from the terminal. Native Swift binary; macOS only.",
5
5
  "keywords": [
6
6
  "apple",