dayone

The dayone binary is a local-first CLI for the Day One service. Everything below — auth, writes, search, sync — runs against a per-profile SQLite store; writes are queued in an outbox and pushed to the server by dayone sync.

Use this top-level page as the index. Open the matching references/<topic>.md only when you need the full flag table or command-specific workflow.

Command tree

!IMPORTANT Every row that lists subcommands above is a group — the command takes the form dayone <group> <subcommand> [flags]. For example:

• dayone search alone is invalid → use dayone search entries --query "X" or dayone search context-items --query "X".
• dayone list alone is invalid → use dayone list entries --journal-id <id> etc.
• dayone auth alone is invalid → use dayone auth login --email ... etc.

Rows marked (terminal command) take flags directly (e.g. dayone sync, dayone tui).

Discover any subcommand and its flags with --help:

dayone --help
dayone auth --help
dayone auth login --help

Common one-liners

Copy-paste shapes for the most frequent tasks. Use these first before drilling into references/ — references only matter when you need a flag not shown here.

# ── Always sync first before any read (see "Read freshness" below) ──
dayone sync

# ── Recommended desktop setup: keep local data fresh automatically ──
dayone sync-schedule enable --interval-minutes 30
dayone sync-schedule status

# ── Read (local SQLite, instant) ──
dayone list journals
dayone list entries --journal-id <journal-id> --sort desc --sort-method entryDate
dayone list entries --journal-id <journal-id> --fields id,date,tags,body
dayone search entries --query "running"
dayone search entries --query "running" --journal-id <journal-id> --limit 10
dayone search entries --tag travel --favorite                # wildcard mode (no --query)
dayone search context-items --query "tennis"

# ── Write (local-first; follow with `dayone sync` to push) ──
dayone entry write --journal-id <journal-id> --body "Today was great."
printf '%s' 'Draft from stdin' | dayone entry write --journal-id <journal-id> --body-stdin
dayone daily-chat add --message "Quick thought for today."
dayone journal update --journal-id <journal-id> --name "Renamed" --color "#E74C3C"
dayone sync

# ── Auth & state ──
printf '%s' '<password>' | dayone auth login --email you@example.com --password-stdin
dayone auth whoami
dayone profile list
dayone profile set staging

Output shapes & jq recipes

!IMPORTANT Every command prints a JSON object to stdout, never a bare array. Three common jq mistakes:

1. jq '.[] | …' fails with Cannot index boolean with string "x" — top level is { ok, …, items: […] }. Use .items[] (or .messages[] for list daily-chat-messages — that one uses a messages key instead).
2. For search, each hit wraps the real entry/context-item under .item. Use .items[].item.body, not .items[].body. Hit envelope: { id, similarity, item }.
3. Entry date is epoch milliseconds — (.date / 1000 | todate) or, inside a search hit, (.item.date / 1000 | todate) for RFC3339.

Canonical recipe covering all three (adapt and reuse):

dayone search entries --query "running" --sort entryDate --direction desc --limit 5 \
  | jq '.items[] | {id, similarity, date: (.item.date / 1000 | todate), body: .item.body[:200]}'

Write commands (entry write, comment write, context-item put, daily-chat add, memory process) return a flat object with ok, the resource id (entry_id, comment_id, …), queued, synced, outbox_id — no items wrapper.

Full envelopes and per-command recipes live in the references: list.md, search.md.

Endpoint precedence (applies to every command)

In order of priority:

1. --api-host <url> flag on the command
2. DAYONE_API_HOST environment variable
3. Active SQLite profile (dayone profile list shows it)

Read freshness

list, search, and tui read only local SQLite — never the network — and the CLI exposes no "last synced at" timestamp, so freshness can't be checked programmatically.

!IMPORTANTRun dayone sync once at the start of any session that will read journal data, before the first list/search/tui call. Skip only when the user explicitly opts out ("from cache", "use local data", "skip sync"). Within a session no need to re-sync between successive reads unless a write happened in between (in which case re-sync to flush the outbox).

Incremental sync on an established account is fast; the "long-running" warning in references/sync.md mostly applies to fresh accounts and first syncs. For normal desktop use, recommend dayone sync-schedule enable --interval-minutes 30 so local reads stay fresh without manual syncs.

Local-first write model

Every write command — entry write, entry delete, comment write|update|delete|react|unreact, context-item put|delete, daily-chat add, journal create, journal update, memory process — persists locally with needs_sync=1 and enqueues a durable outbox item. Run dayone sync after writes to push to the server.

Recommended write flow:

dayone sync            # 1. pull latest server state
# ... your write commands ...
dayone sync            # 2. push queued changes
# optional: verify with `dayone list ...` or `dayone comment list --refresh`

!CAUTION Newly created journals are assigned a pending-… id until the outbox is flushed. After dayone sync the server returns a numeric id. Commands scoped by journal (e.g. list entries --journal-id …) need the resolved id from list journals. Using the pending-… id silently returns no rows.

Output and safety rules

• Output is JSON-first for every command. Pipe it through jq for human reading.
• list, search, and tui read local SQLite only — they never hit the network.
• Never log or echo --password, --key, encryption keys, or API tokens. Prefer --password-stdin / --key-stdin over the flag forms.
• The CLI does not prompt for confirmation on destructive operations. The calling tool MUST require explicit human confirmation before:
  • auth logout --force
  • entry delete
  • comment delete
  • context-item delete
  • Any command run against a production profile or --api-host https://dayone.me
• Prefer --api-host for one-off calls and profile set for persistent environment selection.