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 +75 -15
- package/bin/journal-cli +0 -0
- package/package.json +1 -1
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
|
|
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
|
|
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,
|
|
68
|
-
first
|
|
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
|
-
#
|
|
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" #
|
|
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
|
-
- **
|
|
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
|
|
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
|
|
163
|
-
|
|
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
|
|
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
|
|
205
|
-
|
|
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
|