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 +230 -0
- package/bin/journal-cli +0 -0
- package/package.json +37 -0
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.
|
package/bin/journal-cli
ADDED
|
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
|
+
}
|