Reading items and history
Everything in a complete repository is read through three commands:
synck item list, synck item show and synck item export. They never change
the repository, need no author or account, and never contact the service that
produced it. The examples use the sample
repository from the tutorial.
Pointing at a repository
Every item command takes --path to name the repository directory. Without
it, the current directory is used:
$ synck item list --path launch-project
$ cd launch-project && synck item list
The two commands are equivalent. The item commands always answer in JSON,
designed for scripts and other programs. The examples here use
jq to pick out fields, but any JSON tool will do.
Listing items
With no other options, item list shows the top level of the folder tree:
$ synck item list --path launch-project | jq -r '.items[] | "\(.item_type)\t\(.name)\t\(.item_id)"'
FOLDER Launch 01a1a3eb-9726-7013-bfd0-bb59a731f352
To list a folder’s contents, pass the folder’s path or ID with --parent:
$ synck item list --parent Launch --path launch-project | jq -r '.items[] | "\(.item_type)\t\(.name)"'
FILE budget.csv
FILE proposal.txt
Records, such as chats,
email, posts, tasks and calendars, are never part of the folder tree, so these
listings never show them. --records lists them instead: every record, or with
--parent, the records filed in that folder by a link.
$ synck item list --records --path launch-project | jq -c '.items[0]'
{"created_at":"2026-11-04T00:18:08.304365Z","created_by":"Maria","federation_stream_id":null,"head_seq":5,"item_id":"01a1a3eb-972f-7227-8c51-fe4369603984","item_type":"CHAT","lifecycle_state":"LIVE","link_folder_id":null,"name":null,"name_key":null,"parent_folder_id":null,"record_key":null,"ref_head_seq":0,"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","sequencing_mode":"LOCAL"}
Each entry in items describes one live item, meaning it is not in the
trash. The fields you will use most are:
| Field | Meaning |
|---|---|
item_id |
The permanent ID you pass to other commands |
item_type |
FILE, FOLDER, CHAT, EMAIL, … |
name |
A tree item’s current name. A record has none; its title is in item show |
parent_folder_id |
A tree item’s containing folder, or null at the top level |
link_folder_id |
The folder a record is filed in, or null |
record_key |
A record’s unique key, if it has one |
head_seq |
The position of the item’s latest event in its own history |
created_by, created_at |
Who created it, and when |
sequencing_mode |
LOCAL for most items. Others are sequenced by an external authority; see taking over |
Tree items are listed in name order, and records in the order they were
created. item list shows what is live now. It is not a list of everything
that ever existed. Earlier states are covered below.
Paging through large folders
A listing returns at most 100 items by default. --limit changes the page size
(1 to 512). When there may be more items, next_cursor is not null. Pass it
back, exactly as returned, to --after to get the next page:
$ synck item list --limit 1 --parent Launch --path launch-project | jq -c '{names: [.items[].name], next_cursor}'
{"names":["budget.csv"],"next_cursor":{"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","parent_item_id":"01a1a3eb-9726-7013-bfd0-bb59a731f352","through_repo_seq":null,"name_key":"budget.csv","item_id":"01a1a3eb-974a-770b-91d3-a518ea5dbef8"}}
$ CURSOR=$(synck item list --limit 1 --parent Launch --path launch-project | jq -c '.next_cursor')
$ synck item list --limit 1 --parent Launch --after "$CURSOR" --path launch-project | jq -c '{names: [.items[].name], next_cursor}'
{"names":["proposal.txt"],"next_cursor":null}
A page of records has a plain item ID as its next_cursor; pass that to
--after in the same way. Keep the same --parent and --through for every
page of one listing. Pages of the current state are separate reads. If
someone writes to the repository between them, a later page reflects that
write. When you need a listing that cannot change underneath you, page through
a fixed checkpoint with --through.
Reading an item
synck item show rebuilds one item from its history and returns it. Name a
file or folder by its path or ID, and a record by its ID:
$ synck item show Launch/proposal.txt --path launch-project | jq '.item.projection | {name, size, content_item_seq, last_updated_by, last_updated_at}'
{
"name": "proposal.txt",
"size": 110,
"content_item_seq": 2,
"last_updated_by": "Maria",
"last_updated_at": "2026-11-04T00:18:08.340447Z"
}
The result has the same overall shape for every kind of item:
| Part | What it holds |
|---|---|
item.projection |
Fields every item has: type, name (a record’s title), parent, lifecycle, metadata, current content hash and size for files, and who last changed it |
item.subitems |
The item’s inner records, such as chat messages, reactions and attachments, or an email’s attachments, each with its author, time and content |
item.chat |
A chat’s title, kind and participants |
refs |
The item’s attached ledger, such as a file’s named versions |
item.presentation_warnings |
Anything the reader could not present. Empty when everything was understood |
Synck’s readers present files, folders, chats and email. Other records that
SynckHub stores, such as posts, task lists and tasks, calendars, calls,
contacts and time tracking, are kept, verified and copied exactly like
everything else, but this version of Synck does not present them: item show
on one fails with an unsupported readable state error that names the item
type. synck repository log still lists their events.
Conversations
A chat’s title and kind are in item.chat:
$ synck item show 01a1a3eb-972f-7227-8c51-fe4369603984 --path launch-project | jq -r '.item.chat | "\(.title) (\(.profile.chat_kind))"'
Launch review (ROOM)
SynckHub’s chat kinds are ROOM for team chats, DIRECT for direct messages
between two people, and ASSISTANT_DIRECT for a conversation with an AI
assistant. Its messages are the chat’s subitems, oldest first:
$ synck item show 01a1a3eb-972f-7227-8c51-fe4369603984 --path launch-project | jq -r '.item.subitems[] | "\(.created_at) \(.sender_id): \(.body)"'
2026-11-04T00:18:08.323316Z Sam: Please check the budget before Friday.
2026-11-04T00:18:08.348328Z Maria: The revised figures are ready. Fit-out was missing.
2026-11-04T00:18:08.358668Z Sam: Approved. Send it to the client.
Each message also records its lifecycle (live or deleted) and the message it
replies to, if any. Reactions and attachments are subitems of their own,
linked to their message through parent_item_seq.
Workspaces
A SynckHub workspace (a case, matter, deal or project) is a folder whose
metadata holds a workspace object, with the workspace’s kind and its
workflow state:
$ synck item show Launch --path launch-project | jq -c '{name: .item.projection.name, workspace: .item.projection.metadata_json.workspace.kind, warnings: .item.presentation_warnings}'
{"name":"Launch","workspace":"STANDARD_CASE","warnings":[]}
Each change to its workflow state, such as moving to another stage or closing
it, is a FOLDER::SET_METADATA event in the folder’s own history, so
--through shows the state at any point. Running workflows is SynckHub’s job.
Synck preserves and verifies the state, and does not act on it. The
workspace’s files are its ordinary folder contents.
The records that belong to a workspace are filed in it by a link, and
synck item list --records --parent lists them. SynckHub files a chat through
a small LOCAL_COMPANION record instead, whose key is the chat’s item ID and
whose link is the workspace, so a shared chat can be filed differently in each
repository that has it. The chat itself is listed with every other record.
Saved email is read the same way. An email is a record, listed with
--records, and item show on it returns its headers, references to its
stored original message, and one EMAIL::ATTACHMENT subitem per attachment.
synck item export writes the original .eml or .msg file back out exactly
as it was saved. Synck preserves stored mail. It does not send or receive mail
or connect to a mailbox.
Attachments
Attachments appear as references inside an item, each with a name, a size and
the hash of its content. synck item export extracts FILE items and the
original files of email items. It is not a general attachment exporter. Programs that embed the Synck library can read
attachment content through its verified content readers.
When the reader cannot present something
If a repository contains an event that this version of Synck does not know how
to present, item show says so in presentation_warnings, and for an item
type it does not present at all, it fails with an error. Either way, the
underlying history is still preserved exactly, and it is still verified and
copied. An unknown record is never dropped.
Extracting files
synck item export FILE DESTINATION writes a file’s content to a new file:
$ synck item export Launch/proposal.txt proposal.txt --path launch-project
{"bytes":110,"destination":"proposal.txt","item_id":"01a1a3eb-9737-7051-8189-c2dc29a0d474","schema_version":1}
Synck verifies the content’s size and SHA-256 before writing. The destination
must not exist, and its folder must. Existing files are never overwritten. To
extract every file in a folder, combine list and export:
synck item list --parent Launch --path launch-project |
jq -r '.items[] | select(.item_type=="FILE") | "\(.item_id) \(.name)"' |
while read -r id name; do
synck item export "$id" "out/$name" --path launch-project
done
To get ordinary editable files for a whole repository, a checkout is usually more convenient.
Reading the past
Every item command accepts --through N to read the repository as it was at
the end of position N in its history:
$ synck item export Launch/proposal.txt proposal-first-draft.txt --through 5 --path launch-project
{"bytes":91,"destination":"proposal-first-draft.txt","item_id":"01a1a3eb-9737-7051-8189-c2dc29a0d474","schema_version":1}
$ synck item show 01a1a3eb-972f-7227-8c51-fe4369603984 --through 5 --path launch-project | jq -r '.item.subitems[] | "\(.sender_id): \(.body)"'
Sam: Please check the budget before Friday.
$ synck item list --through 2 --path launch-project | jq -r '.items[] | "\(.item_type) \(.name) (\(.head_seq) events)"'
FOLDER Launch (2 events)
--records is the one exception: it lists only the current records, so read
an earlier state of a record with item show --through and its ID.
N is a repository sequence, the position of a commit in the repository’s
overall history. It is not a file’s item sequence and not a commit ID. The
position must be a sealed checkpoint, meaning one that the history has fully
reached:
$ synck item list --through 99 --path launch-project
synck: historical sequence is not a sealed repository checkpoint
synck repository verify reports the latest checkpoint as
terminal_repo_seq. Historical listings are fixed: paging through a
checkpoint always returns the same items, however the repository changes
afterwards.
Finding the right checkpoint
synck repository log lists the repository’s commits, newest first, with the
events in each one:
$ synck repository log launch-project --limit 3 | jq -r '.commits[] | "\(.repo_seq) \(.author) \(.created_at) \([.events[].event_type] | join(", "))"'
8 Sam 2026-11-04T00:18:08.358668Z CHAT::MESSAGE::CREATE
7 Maria 2026-11-04T00:18:08.348328Z CHAT::MESSAGE::CREATE
6 Maria 2026-11-04T00:18:08.340447Z FILE::SET_CONTENT
Each commit has its repo_seq, which is the number to pass to --through, plus
its commit_id, author, committer, time and message. Each event names its
item_id, its position (seq) in that item’s history, its type and its
ledger: ITEM for the item’s own history, REF for its ref
ledger. Commit 3, for
example, created the proposal and its first named version:
$ synck repository log launch-project --limit 1 --before 4 | jq -c '.commits[0].events[] | {item_id, seq, event_type, ledger}'
{"item_id":"01a1a3eb-9737-7051-8189-c2dc29a0d474","seq":1,"event_type":"FILE::CREATE","ledger":"ITEM"}
{"item_id":"01a1a3eb-9737-7051-8189-c2dc29a0d474","seq":1,"event_type":"FILE_VERSION::CREATE","ledger":"REF"}
To find when the proposal changed, look for FILE::CREATE and
FILE::SET_CONTENT events with the proposal’s ID.
A page holds 20 commits unless you set --limit (1 to 512). For older commits,
pass the page’s next_before back as --before:
$ synck repository log launch-project --limit 3 | jq .next_before
6
$ synck repository log launch-project --limit 3 --before 6 | jq -r '.commits[] | "\(.repo_seq) \(.author) \([.events[].event_type] | join(", "))"'
5 Maria FILE::CREATE, FILE_VERSION::CREATE
4 Sam CHAT::MESSAGE::CREATE
3 Maria FILE::CREATE, FILE_VERSION::CREATE
next_before is null on the page with the first commit.