Add Apple Music listening history (what played and when)

[jmcte]

Goal

Add a read-only icloud-cli surface that shows what the authenticated user listened to in Apple Music and when it was played.

Proposed CLI

icloud music history
icloud music history --limit 50
icloud music history --since 2026-07-01
icloud music history --json

The exact command name may change to match existing CLI conventions.

Required output

For each available listening event, return:

• track/song title
• artist
• album, when available
• playback timestamp, including timezone or an unambiguous UTC value
• Apple Music/catalog identifier, when available
• source/type where useful (song, station, playlist, etc.)

Results should be newest first and support bounded pagination or a limit.

Investigation notes

Apple's recently played APIs may expose only recent resources rather than a complete timestamped event log. Before implementation, verify:

1. whether MusicKit / Apple Music API returns per-play timestamps;
2. the maximum history window and pagination behavior;
3. required Apple Music authorization and entitlements;
4. whether macOS-local Music data can safely supplement missing timestamps without relying on brittle or destructive access.

If Apple does not expose exact per-play times, document the limitation clearly and return the best truthful data available. Do not synthesize timestamps.

Privacy and safety

• Read-only: no library or playback mutations.
• Keep raw listening history local to Hermes/OpenClaw unless the user explicitly exports it.
• Do not log credentials, developer tokens, user tokens, or full raw API payloads.
• Fail clearly when Apple Music authorization is missing or expired.

Acceptance criteria

• A documented command returns recently played Apple Music items.
• Human-readable and structured JSON output are supported.
• Exact playback time is included when the source provides it.
• Missing timestamps are represented honestly, not inferred.
• Limit/pagination behavior is bounded and tested.
• Authorization failures have actionable messages.
• Unit tests cover parsing, ordering, timestamp handling, pagination, and redaction.
• Documentation states the available history window and Apple API limitations.

Future use

This will feed a private OpenClaw “media history” view alongside Apple Books progress and a future Audible listening-history connector.

[jmcte]

Investigation result: blocked pending an Apple Music API decision

Per the issue's "verify before implementation" step, I inspected the real local Apple Music data (read-only) on macOS. The headline requirement — "what played and when" — cannot be satisfied from local data, and this repo has no Apple Music API/MusicKit integration to fall back on.

Local sources inspected

Source	Format	What it actually contains
~/Music/Music/Music Library.musiclibrary/Preferences/History.dat	XML plist (~146 MB)	items.iar = a bounded ~200-item recently-played list. Per item: track name, contentDesc.kind (e.g. song), and identifiers (storeAdamID, storeCloudID, storeCloudAlbumID, cloudUniversalLibraryID, libraryItemID). The bulk of the file is embedded artwork (art.artDat base64 PNGs).
~/Music/Music/Music Library.musiclibrary/Library.musicdb	proprietary hfma (not SQLite)	Main library; not safely readable as SQLite. This is why existing music commands fail closed on it.
.../com.apple.MusicKit/downloaded_catalog_data/MusicCatalogData.db	SQLite	catalog_song keyed by adam_id: duration, all_genres, added_date, last_updated_date, audio-analysis fields. No artist/album names, no play timestamps.
.../Extras.itdb	SQLite	cddb/uits identifier tables only. No history.

Key constraints (the truthful picture)

• No per-play timestamps exist locally. History.dat is an ordered recently-played list with no playedAt/date fields anywhere in its key vocabulary.
• No artist or album names locally — only IDs (storeAdamID, storeCloudAlbumID, etc.). MusicCatalogData.db does not carry artist/album text either.
• Bounded window: the local store retains ~200 recent items, not a complete event log.
• No API path in-repo: there is no MusicKit / Apple Music API client, developer token, user token, or entitlement anywhere in this offline, read-only tool. Adding one is a network + credentials + entitlement effort well outside the current architecture.

This matches the issue's own anticipation: "Apple's recently played APIs may expose only recent resources rather than a complete timestamped event log" and "If Apple does not expose exact per-play times, document the limitation clearly... Do not synthesize timestamps."

Decision needed to unblock

The acceptance criteria hinge on exact playback time and artist/album, which require the Apple Music API (MusicKit) "recently played" / play-history endpoints with a developer token + user (MusicKit) token and the appropriate entitlement. That is a governance/architecture decision (network access, credential handling, entitlements) rather than a local-read implementation.

Options for the orchestrator/gate:

1. Approve an Apple Music API integration (MusicKit user token + developer token, entitlements, token storage/redaction policy). Note: Apple's recently-played endpoint returns recent resources and historically does not provide reliable per-play timestamps either — this must be verified against the live API before committing to the "and when" requirement.
2. Accept a reduced local-only scope — a music history that returns title, kind/source-type, and catalog IDs with playedAt, artist, and album honestly null (optionally enriched with duration/genres from MusicCatalogData.db via adam_id), with --since documented as unsupported. This satisfies the acceptance criteria as written ("exact time included when the source provides it"; "missing timestamps represented honestly, not inferred") but not the headline intent.
3. Keep blocked until the API/entitlement decision is made.

Marking blocked / human decision required. No code was changed; investigation was read-only against the local Music library.

[jmcte]

API verification: Apple Music API also does not expose per-play timestamps

Follow-up to the local-data investigation. I verified the Apple Music API against Apple's primary documentation. Direction is to move forward with API integration, so this records exactly what the API can and cannot deliver before any networked/credentialed code is written.

Endpoints (all require a Music User Token)

Endpoint	Path	Returns
Get Recently Played Resources	GET /v1/me/recent/played	Ordered Resource[] (songs, albums, stations, playlists). Paginated via next + offset.
Get Recently Played Tracks	GET /v1/me/recent/played/tracks	Ordered Resource[] of songs.
Get Recently Played Stations	GET /v1/me/recent/played/stations	Ordered Resource[] of stations.
Get Heavy Rotation Content	GET /v1/me/history/heavy-rotation	Ordered Resource[].
Get Recently Added Resources	GET /v1/me/library/recently-added	Library adds; carries dateAdded (a library-add date, not a play date).

What the API gives us (better than local)

For a played song, attributes include: name, artistName, albumName, genreNames, trackNumber, discNumber, durationInMillis, releaseDate, isrc, composerName, artwork, url, playParams, plus the catalog id. Stations/albums/playlists return their equivalent resource attributes. The list order is the recency signal, and next/offset give bounded pagination.

What the API does NOT give us (the blocking fact)

There is no per-play timestamp. The documented response schema for the recently-played/history endpoints contains no playedAt, lastPlayedDate, play-time, or any date attribute on the played items. The only ordering is the implicit array order. "Get the user's replay data" returns aggregate period summaries (top songs/artists/albums for a year), not timestamped events.

Conclusion: No Apple-sanctioned surface — local stores or the Apple Music API — provides a timestamped per-play event log. The issue's headline requirement, "what played and when", is only half-achievable: we can return what played (with full artist/album/title metadata and recency ordering via the API), but when (exact playback time) is not available and must remain null rather than be synthesized. This is strictly better metadata than the local History.dat path (which lacks artist/album names), but the timestamp limitation is identical.

Integration prerequisites (credentials/entitlements — operator-supplied)

1. Apple Developer Program membership with a registered MusicKit identifier.
2. Developer token: a JWT (ES256) minted from a MusicKit private key (.p8), key id, and team id. Requires secret storage and rotation; must never be logged.
3. Music User Token: required for every /v1/me/... call. Apple documents this as automatically managed by MusicKit for Apple-platform apps and web apps — there is no supported user-auth flow for a bare SwiftPM CLI executable. Options are (a) a real .app host with the MusicKit capability + user authorization, or (b) harvesting a user token from MusicKit-on-the-web and injecting it. Tokens expire and need refresh through the app framework. This is the largest unresolved engineering hurdle.

Governance intersection

• ADR-001 (docs/adr/001-execution-model.md) states the default "remains local-only and read-only," and any action beyond that "requires a separate issue, namespace, authorization design, audit contract, and permission boundary." A networked, credentialed client is a new network-egress + secrets surface, even though the calls themselves are read-only GETs.
• This directly intersects Decide the provider, helper, and daemon execution model #83 (execution model), still OPEN and autonomy:human-required, needing architecture/security/product approval.
• A networked API provider would be a new provider classification ("delegated integration"/network) in icloud-cli.providers.v1 and ADR-001's classification table, plus privacy/redaction updates (developer token, user token, and raw payloads must never be logged — already an issue requirement).

Recommendation

Because the timestamp requirement is unachievable via the API as well, re-scope #112 to what Apple actually provides: a music history returning recently-played resources (title, artist, album, kind/source-type, catalog id, ISRC, duration, artwork ref) in recency order with bounded pagination, playedAt honestly null, and documentation stating the limitation. Proceeding still requires: (1) operator-provisioned Developer Program + MusicKit key, (2) a chosen Music User Token strategy for a CLI, and (3) architecture/security sign-off under #83/ADR-001 for the network+secrets surface.

[jmcte]

Re-scoped: design-first ADR opened (PR #119)

Per the decision to proceed with API integration, #112 is re-scoped and a design-first ADR is up for review (documentation only — no implementation code):

• PR: docs: propose Apple Music API network provider ADR (ADR 002) #119 — docs: propose Apple Music API network provider ADR (ADR 002)
• ADR: docs/adr/002-apple-music-api-network-provider.md (status: proposed; approval-gated)

What the ADR locks in

• music history returns recently-played resources (title, artist, album, kind/source-type, catalog id, ISRC, duration), newest-first, with bounded pagination/limit; playedAt is honestly null; --since is rejected with an actionable message because Apple provides no per-play timestamps.
• Read-only, opt-in network provider (GET-only to api.music.apple.com); no mutation; defaultPolling: false.
• Secrets/redaction: .p8 + developer/user tokens never committed, persisted, or logged; raw payloads not logged.
• Provider-manifest changes (incl. the new network sourceKind question) + ADR-001 classification update; tests-first plan with fixture-backed parsers (no live network or real tokens in CI).

Blocking before any implementation

1. Music User Token strategy for a bare CLI — the feasibility crux (injected harvested token vs. signed .app MusicKit host vs. web harvest).
2. Non-author architecture/security/product approval + an explicit VISION.md local-only boundary change.
3. Resolution of Decide the provider, helper, and daemon execution model #83 as it applies to networked providers.
4. Operator credentials: Apple Developer Program + MusicKit .p8 (key id / team id).

#112 stays blocked / human-required until ADR 002 is accepted and credentials exist. The 5 open decisions and review live on PR #119.

[jmcte]

ADR 002's open questions are resolved per the product owner (2026-09-24) and pushed to PR #119:

• Music User Token → operator-injected harvested token (env/Keychain); no interactive auth flow in the CLI.
• sourceKind → add network (additive; no schema bump).
• music history requires --confirm-sensitive.
• Network-only for v1 (no local MusicCatalogData.db enrichment).
• No local cache for v1.

#112 stays blocked / human-required pending non-author architecture + security approval, the VISION.md boundary change, #83 resolution for networked providers, and operator credentials (Apple Developer Program + MusicKit .p8). No implementation until ADR 002 is accepted.