apple-journal-cli 1.0.3

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 ADDED
@@ -0,0 +1,230 @@
1
+ # journal-cli
2
+
3
+ **Read and write Apple Journal entries from the terminal.** Text, photos,
4
+ videos, Live Photos, web links, location pins, bookmarks, multiple journals —
5
+ plus search, Markdown/JSON export, and audio transcripts. Native Swift, zero
6
+ dependencies, macOS 14+.
7
+
8
+ Apple Journal has no public API, no AppleScript dictionary, and no export
9
+ format worth scripting against. journal-cli talks directly to the app's own
10
+ data store, safely: reads never touch the live database, writes are guarded,
11
+ backed up, and verified against Journal's sync engine.
12
+
13
+ ```
14
+ $ journal-cli list --limit 3
15
+ 117 2026-08-21 00:43:01 Test new features
16
+ 116 2026-08-21 00:32:11 link test
17
+ 115 2026-08-20 22:16:40 test journal routing
18
+
19
+ $ journal-cli show 117
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)
22
+ ```
23
+
24
+ ## Install
25
+
26
+ ```sh
27
+ brew install omarshahine/tap/journal-cli
28
+ # or
29
+ npm install -g apple-journal-cli
30
+ # or from source
31
+ git clone https://github.com/omarshahine/journal-cli && cd journal-cli/swift
32
+ swift build -c release && cp .build/release/journal-cli /usr/local/bin/
33
+ ```
34
+
35
+ Grant **Full Disk Access** to your terminal (System Settings → Privacy &
36
+ Security), then:
37
+
38
+ ```sh
39
+ journal-cli doctor
40
+ ```
41
+
42
+ ## Reading
43
+
44
+ Reads run against a temp snapshot of the store, so they are safe while
45
+ Journal.app is open and never lock the live database.
46
+
47
+ ```sh
48
+ journal-cli list --limit 20 --full # --full prints bodies
49
+ journal-cli list --since 2025-01-01 --until 2025-12-31
50
+ journal-cli show 95 # entry + assets + attachment paths
51
+ journal-cli search anguilla
52
+ journal-cli export --dir ~/journal-export # one .md per entry, YAML frontmatter
53
+ journal-cli export --dir ~/export --format json
54
+ journal-cli stats # counts, words, by-year histogram
55
+ journal-cli journals # list journals
56
+ journal-cli deleted # list Recently Deleted
57
+ ```
58
+
59
+ `show` decodes everything Journal stores: entry text, titles, bookmark state,
60
+ photo/video attachment paths, location pins with place names, web links with
61
+ titles, **audio transcripts** (word-level, joined), and handwriting-recognition
62
+ text from drawings.
63
+
64
+ ## Writing
65
+
66
+ 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,
69
+ including CloudKit accepting attached files.
70
+
71
+ ```sh
72
+ # text, dated, bookmarked
73
+ journal-cli write --live --title "Monday" --body "Long run, then coffee." \
74
+ --date 2026-08-01 --bookmark
75
+
76
+ # photos and video (images auto-downscale to Journal's own ~6MP cap)
77
+ journal-cli write --live --body "Beach day" --media a.heic b.mov
78
+
79
+ # a Live Photo is an image + video pair
80
+ journal-cli write --live --body "Golden hour" --live-photo IMG_0123.heic IMG_0123.mov
81
+
82
+ # location pin
83
+ journal-cli write --live --body "At the office" \
84
+ --lat 47.62055 --lon -122.34930 --place "Space Needle" --city Seattle
85
+
86
+ # web link (renders as a rich link card)
87
+ journal-cli write --live --body "Read this" --link https://example.com --link-title "A Post"
88
+
89
+ # target a journal; link photos back to the Photos library
90
+ journal-cli write --live --journal "Travel" --body "..." --media IMG_0079.JPG --photos-link
91
+ ```
92
+
93
+ ### Editing
94
+
95
+ ```sh
96
+ journal-cli edit 103 --live --body "Rewritten." --title "New title"
97
+ journal-cli edit 103 --live --lat 47.6 --lon -122.3 --place Home # set/replace pin
98
+ journal-cli edit 103 --live --add-media c.heic --add-link https://example.org
99
+ journal-cli edit 103 --live --remove-media 700 # ids shown by `show`
100
+ journal-cli edit 103 --live --clear-location --no-bookmark
101
+ journal-cli edit 103 --live --journal "Travel" # move journals
102
+ ```
103
+
104
+ ### Deleting
105
+
106
+ ```sh
107
+ journal-cli delete 103 --live # soft delete -> Recently Deleted; syncs
108
+ journal-cli restore 103 --live # bring it back; syncs
109
+ journal-cli empty --live # purge never-synced deleted entries
110
+ journal-cli delete 103 --live --hard # full row+file removal (guarded, see below)
111
+ ```
112
+
113
+ ## Agent-friendly by design
114
+
115
+ journal-cli is built to be driven by AI agents and scripts as much as by
116
+ humans:
117
+
118
+ - **`--json` on every read command** — stable keys, machine-parseable, no
119
+ ANSI. `list`, `show`, `search`, `journals`, `deleted` all speak JSON.
120
+ - **Meaningful exit codes** — `0` success, `1` refusal or error, with a
121
+ one-line reason on stderr prefixed `journal-cli:`.
122
+ - **`--help` / `doctor`** — full usage from the binary itself;
123
+ `doctor` reports access state and entry count, exit 1 when setup is needed.
124
+ - **Guardrails an agent cannot stumble past** — destructive or risky paths
125
+ (`--live`, `--force`, `--hard`) must be opted into explicitly, and every
126
+ live write auto-backs-up first.
127
+ - **Sandboxing as a first-class command** — `sandbox --dir D [--from BACKUP]`
128
+ hands back a disposable copy of the store; every other command accepts
129
+ `--db` (or `$JOURNAL_DB`) to target it. Agents can rehearse a write with
130
+ zero risk, then replay it `--live`.
131
+ - **A skill ships in-repo** — `skills/journal-cli/SKILL.md` teaches
132
+ Claude-style agents the command surface, the safety model, and the sharp
133
+ edges.
134
+
135
+ ## Safety model
136
+
137
+ | Layer | Behavior |
138
+ |---|---|
139
+ | Reads | temp snapshot of `db`+`-wal`+`-shm`; live store never opened for read |
140
+ | `--live` gate | writes to the real store refuse to run without it |
141
+ | App check | writes refuse to run while Journal.app is open |
142
+ | Auto-backup | every live write snapshots the store to `~/Backups/journal-cli/` first |
143
+ | Synced hard-deletes | refused without `--force`: a local row delete does not tombstone the CloudKit record, and the entry **resurrects on the next sync** (observed). Soft delete syncs properly. |
144
+ | CRDT text guard | text edits on app-authored entries are refused without `--force` (see below) |
145
+ | Sandbox | `sandbox` + `--db` target a throwaway copy; the `--live` gate does not apply there |
146
+
147
+ ## Verified behavior
148
+
149
+ Every write path has been verified against a real library on macOS 26:
150
+ Journal.app renders CLI-written text, photos, Live Photos (labeled as such),
151
+ link cards, and location pins (which also feed its Places index); the sync
152
+ engine uploads them all to CloudKit — including the attachment files — and a
153
+ delete/restore round trip propagates. The read pipeline has been swept over an
154
+ entire real store: every entry row and all ~700 asset metadata blobs parse.
155
+
156
+ The test suite (`tests/test_write.sh`, 110 assertions) runs the whole command
157
+ surface against a disposable copy of a store — argument guards, insert
158
+ bookkeeping, RTF round-trips, location metadata, media file layout, Live Photo
159
+ pairing, Photos linkage, journal targeting, link assets, the delete/restore
160
+ lifecycle, and `PRAGMA integrity_check`. Point `JOURNAL_SEED` at a backup to
161
+ 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.
164
+
165
+ ## How it works
166
+
167
+ Journal's store is a Core Data SQLite database:
168
+
169
+ ```
170
+ ~/Library/Group Containers/group.com.apple.moments/Library/moments.sqlite
171
+ ```
172
+
173
+ "moments" is Journal's internal codename, which is why searching for "journal"
174
+ never finds it. Entry text is plain RTF in `ZJOURNALENTRYMO.ZTEXT` — not
175
+ encrypted. (The encrypted CloudKit records under the app container are only
176
+ the sync cache.)
177
+
178
+ | Data | Storage |
179
+ |---|---|
180
+ | entries | `ZJOURNALENTRYMO`; text/title as RTF blobs; Core Data epoch timestamps |
181
+ | assets | `ZJOURNALENTRYASSETMO` — 12 types (photo, video, livePhoto, multiPinMap, link, audio, drawing, stateOfMind, streakEvent, workoutRoute/Icon, motionActivity) |
182
+ | files | `ZJOURNALENTRYASSETFILEATTACHMENTMO` → `Attachments/<entryUUID>/<assetUUID>/…` |
183
+ | asset metadata | one version byte `0x01` + JSON; `0x02` + UUID = Core Data external storage in `.moments_SUPPORT/_EXTERNAL_DATA/` |
184
+ | links | base64 `NSKeyedArchiver`-archived `LPLinkMetadata` inside the asset metadata |
185
+ | 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 |
187
+ | 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
+
189
+ ### The CRDT limitation
190
+
191
+ A CRDT (Conflict-free Replicated Data Type) is a data structure built so that
192
+ several devices can edit the same content offline and still merge to an
193
+ identical result, with no server picking winners. Instead of storing "the
194
+ string", a text CRDT stores every character with an identity and causal
195
+ history, so two devices replaying each other's operations always converge.
196
+
197
+ Journal keeps such a CRDT in `ZMERGEABLEATTRIBUTES` (magic `crdt`, a protobuf)
198
+ — a second, richer copy of the entry text alongside the RTF, present on every
199
+ entry whose text was typed in the app. Consequences:
200
+
201
+ - **`edit` refuses to rewrite text on CRDT-bearing entries** unless `--force`
202
+ is passed: rewriting only the RTF leaves the CRDT holding the old text with
203
+ 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).
206
+ - **CLI-written entries have no CRDT.** Journal renders and syncs them fine,
207
+ but a simultaneous edit on two devices may not merge like an app-authored
208
+ entry would.
209
+ - **Authoring the CRDT is out of scope** — fabricating causal history in a
210
+ reverse-engineered protobuf risks corrupting merge for that entry.
211
+
212
+ ### Not supported
213
+
214
+ - Creating system-generated assets: streaks, state of mind, workout data,
215
+ motion activity, drawings. Their metadata all decodes on read.
216
+ - Writing audio entries (transcripts and duration are read).
217
+ - Rendering `PKDrawing` stroke data.
218
+ - Whether a purged CloudKit record is tombstoned on *other* devices has not
219
+ been verified from this machine.
220
+
221
+ ## Development
222
+
223
+ ```sh
224
+ cd swift && swift build # debug build
225
+ tests/test_write.sh # full suite against a store copy
226
+ ```
227
+
228
+ The `reference/` directory holds the original Python implementation — same
229
+ command surface, same test suite, useful for spelunking since it needs no
230
+ build step.
Binary file
package/package.json ADDED
@@ -0,0 +1,37 @@
1
+ {
2
+ "name": "apple-journal-cli",
3
+ "version": "1.0.3",
4
+ "description": "Read and write Apple Journal entries from the terminal. Native Swift binary; macOS only.",
5
+ "keywords": [
6
+ "apple",
7
+ "journal",
8
+ "journaling",
9
+ "macos",
10
+ "cli",
11
+ "diary"
12
+ ],
13
+ "homepage": "https://github.com/omarshahine/journal-cli",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/omarshahine/journal-cli.git"
17
+ },
18
+ "license": "MIT",
19
+ "author": "Omar Shahine",
20
+ "os": [
21
+ "darwin"
22
+ ],
23
+ "cpu": [
24
+ "arm64",
25
+ "x64"
26
+ ],
27
+ "bin": {
28
+ "journal-cli": "bin/journal-cli"
29
+ },
30
+ "files": [
31
+ "bin/journal-cli",
32
+ "README.md"
33
+ ],
34
+ "scripts": {
35
+ "prepack": "mkdir -p bin && cp ../README.md README.md && cp ../swift/.build/apple/Products/Release/journal-cli bin/journal-cli && chmod +x bin/journal-cli"
36
+ }
37
+ }