I'll start by reading the key existing files to understand the patterns, then implement the changes.

Now let me read a few more files to understand the types and EventStore patterns.

Let me check the PartType values and look at existing tests for patterns.

Now let me read the share test for the exact mock patterns, and check the GET endpoints on the API routes.

Let me find the actual API route handler for trace detail and messages GET endpoints.

Now let me check the API response shape for getTrace and listMessages.

Now let me check the API types for the response shapes.

I now have a complete understanding of all the patterns. Let me implement the changes.

First, update cli/src/services/api.ts - add the new types, methods, and reverse transform.

Now add the new types after RemoteTraceSummary:

Now add the fetch functions and reverse transform before the createApi function:

Now add the new methods to the createApi() return object:

Now add the sync command dispatch. I'll add it after the list command:

Now add the sync command to the help text:

One test failure - the store gets created after the API calls, so if the API call throws, the store never gets created. Let me fix the sync command to create the store earlier.

Also fix the finally block to not use optional chaining since store is always defined now:

Now let me check what the other test failure was. Let me look at the output more carefully - it said "2 fail, 1 error". Let me run just the sync tests first, then the full suite.

All 15 sync tests pass. Now let me run the full suite to check the other failures aren't mine.

My sync tests all pass (15 pass, 0 fail). There's 1 pre-existing failure and 1 pre-existing error that aren't related to my changes. Let me verify which ones they are.

The failing test is in setup.ts due to a missing @clack/prompts module, and the error is unrelated to my changes. These are pre-existing issues.

All done. Here's a summary of what was implemented:

cli/src/services/api.ts - Added:

• RemoteTraceDetail and RemoteMessage types for the API response shapes
• getRemoteTrace() and getRemoteTraceMessages() fetch functions
• buildEventFromMessage() reverse transform (inverse of buildMessagePayload) that converts API messages+parts back into CLI TraceEvents
• getTrace() and getTraceMessages() methods on the Api type and createApi() factory

cli/src/commands/sync-options.ts (new) - Positional arg parser for externalId plus --json flag

cli/src/commands/sync.ts (new) - The sync command using the same runtime-injection pattern as share/list. Flow: validate args, check auth, fetch remote trace + messages via API, convert to events, upsert trace metadata and events into local EventStore

cli/src/commands/sync.test.ts (new) - 15 tests covering:

• Missing externalId validation (JSON + human-readable)
• API not configured / unauthenticated errors
• Successful sync with upsert + event replacement verification
• JSON and human-readable output formats
• Correct event type conversion (text, thinking, tool_call, tool_result, error)
• Fallback to textContent when no parts present
• Default agentId to 'manual' when missing
• API 404 mapped to TRACE_NOT_FOUND
• Generic API errors mapped to SYNC_FAILED
• Store cleanup on success and error

cli/src/index.ts - Added sync command dispatch and help text

Same branch — it's all part of the git metadata feature set.

Committed as eb492f3 on feat/git-metadata.

Updated: https://github.com/market-dot-dev/traces/pull/253

Added the sync command section covering the new traces sync command, the reverse transform, and the 15 new tests.

The traces sync command covers the "import by external ID" item and the "verify existing GET endpoint" item. Let me update those checkboxes.

Updated. Checked off traces sync and the GET endpoint verification, removed the separate export endpoint item (since the existing messages endpoint already serves that purpose), and consolidated the import items.

Good call. That would give you trace discovery even without git notes set up locally. Let me check what's already in place for that.

Good, the by_gitRemoteUrl index already exists but nothing queries it yet. Now let me read the key files I need for the plan.

Now let me read the hook file and the useAppState.ts to understand the TUI startup sequence and where we'd plug in.