Command reference
This page lists every synck command, grouped by what you use it
for. Each group links to the guide that explains it. For the exact options of
the binary you have installed, use synck --help and synck COMMAND --help.
synck instructions prints a compact operating guide.
Conventions. UPPERCASE words are values you supply. Square brackets mark
optional parts; do not type the brackets. ... means the argument can be
repeated. Quote values that contain spaces. The global option --json goes
before the command name, as in synck --json status. See
Output, JSON and exit codes.
Other reference pages: Formats and compatibility · Output, JSON and exit codes · Glossary · Questions and answers
Revisions
Commands that take REVISION, FROM or TO accept:
| Form | Meaning |
|---|---|
HEAD |
The latest commit |
HEAD~N |
N commits before the latest, counting actual commits |
N |
The commit at repository sequence N |
sha256:… |
The commit with exactly this full ID |
Abbreviated IDs, branch names and other Git revision expressions are not supported. See Naming a commit.
Creating and inspecting a repository
| Command | Purpose |
|---|---|
synck init [DIRECTORY] --author AUTHOR [--storage-mode CHUNKED|WHOLE_FILE] |
Make a directory, by default the current one, a repository with a checkout, and commit its .synckignore. Existing files stay uncommitted |
synck info |
Show the repository’s root, format, ID, author and latest commit |
synck context |
info, plus current changes and recent commits |
synck config author |
Show the author for future commits |
synck config set-author AUTHOR |
Change the author for future commits |
synck config hidden-files |
Show whether untracked hidden files are ignored or tracked |
synck config set-hidden-files ignore or ... track |
Change that setting |
synck instructions |
Print a compact operating guide, for people and AI agents |
synck repository init is another name for synck init. Guide: Your first
repository, Recording
changes.
Recording changes
| Command | Purpose |
|---|---|
synck status |
List every uncommitted change |
synck diff |
Show text changes not yet committed |
synck commit [-m MESSAGE] [PATH ...] |
Commit all changes, or only those under the named paths |
synck commit --batch [-m MESSAGE] [PATH ...] |
Commit a very large change as several commits; only when commit asks you to |
synck mv SOURCE DESTINATION -m MESSAGE |
Move or rename a tracked item and commit it, from a clean working tree |
There is no add and no staging area. Saved .eml and .msg files are
committed as email items. Guide: Recording
changes, Moving, renaming and
deleting, Committing large
folders.
Viewing history
| Command | Purpose |
|---|---|
synck log [-n COUNT] [--oneline] |
List commits, newest first |
synck log [-n COUNT] --events |
List commits with their exact events |
synck show REVISION [--events] |
Show one commit |
synck history PATH |
Show every commit that affected one live item, through renames and moves |
synck versions PATH |
List a file’s content versions with their item sequences |
synck diff FROM TO |
Show text changes between two revisions |
synck compare FROM TO |
Show structural changes between two revisions |
-n can also be written --limit. diff takes zero or two revisions. These
commands show files and folders; synck repository log shows every event.
Guide: Viewing history.
Getting content out
| Command | Purpose |
|---|---|
synck export PATH NEW_FILE [--item-seq N] |
Write a live file’s latest, or selected, committed content to a new file |
synck export-tree REVISION NEW_DIRECTORY [--folder PATH] |
Write the files and folders of a revision to a new directory |
Destinations must not exist. Guide: Undoing things.
Undoing
| Command | Purpose |
|---|---|
synck restore PATH [--item-seq N] |
Replace a file in the working tree with committed content. Discards uncommitted edits to it |
synck restore-tree |
Return the whole working tree to the latest commit. Discards all uncommitted changes |
synck revert REVISION -m MESSAGE |
Add a commit that reverses an earlier one that changed only files and folders |
synck deleted |
List items in the trash |
synck recover PATH_OR_ITEM_ID -m MESSAGE |
Bring an item back from the trash, keeping its identity |
recover takes the path the item had when it was deleted, or its item ID from
deleted when several deleted items had the same path. Guide: Undoing
things.
Named versions
| Command | Purpose |
|---|---|
synck version list PATH [--all] |
List a file’s named versions; --all includes removed ones |
synck version create PATH [--item-seq N] [--major] [--description TEXT] -m MESSAGE |
Name the current, or a selected, version |
synck version set-description PATH VERSION_ID --description TEXT -m MESSAGE |
Replace a description; an empty value clears it |
synck version promote PATH VERSION_ID -m MESSAGE |
Make a named version major |
synck version demote PATH VERSION_ID -m MESSAGE |
Make a named version minor |
synck version tombstone PATH VERSION_ID -m MESSAGE |
Remove a label permanently; the file version remains |
synck version restore PATH VERSION_ID |
Copy a named version’s content into the working tree, without committing |
Guide: Named versions.
Reading items
These commands read any repository, with or without a checkout. The repository
is the current directory unless you pass --path DIRECTORY. They print JSON.
| Command | Purpose |
|---|---|
synck item list [--parent FOLDER_ID] [--limit COUNT] [--after CURSOR] [--through N] [--path DIRECTORY] |
List live items at the top level or in a folder |
synck item show ITEM_ID [--through N] [--path DIRECTORY] |
Read one item, including messages and refs |
synck item export ITEM_ID NEW_FILE [--through N] [--path DIRECTORY] |
Write a file’s content, or an email’s original message, to a new file |
For item list, --limit defaults to 100 and accepts 1 to 512. Pass
next_cursor from one page to --after for the next, as a single JSON
argument. --through takes a sealed repository sequence. Guide: Reading items
and history.
Email and chats
| Command | Purpose |
|---|---|
synck commit on .eml or .msg files |
Record each message as an email item |
synck repository create-chat TITLE [--path DIRECTORY] |
Create a chat |
synck repository append-chat CHAT_ID BODY_FILE [--attachment FILE ...] [--path DIRECTORY] |
Add a UTF-8 message to a chat, with optional attachments |
Guide: Email and chats.
Integrity, storage and backups
| Command | Purpose |
|---|---|
synck fsck [--rebuild-state-index] |
Verify the repository; optionally rebuild the history index first |
synck repository verify [DIRECTORY] |
Verify the repository in DIRECTORY |
synck storage |
Report referenced and unreachable stored content |
synck gc |
Delete stored content that no commit refers to |
synck storage optimize |
Convert whole-file storage to chunked storage in place |
synck archive NEW_DIRECTORY [--storage-mode CHUNKED|WHOLE_FILE] |
Write a verified copy of the repository |
synck monitor start, status, stop |
Manage the optional background monitor |
fsck and repository verify run the same checks. Guide: Backup and
recovery, Storage
space.
Copies
| Command | Purpose |
|---|---|
synck repository import SOURCE NEW_DIRECTORY [--storage-mode CHUNKED|WHOLE_FILE] |
Make a verified copy, as a follower |
synck repository archive NEW_DIRECTORY [--path DIRECTORY] [--storage-mode CHUNKED|WHOLE_FILE] |
The same, naming the source with --path |
synck repository log [DIRECTORY] [--limit COUNT] [--before N] |
List commits newest first, with all their events, as JSON |
Copies keep the source’s storage layout unless you pass --storage-mode. For
repository log, --limit defaults to 20 and accepts 1 to 512, and --before
takes the previous page’s next_before. Guide: Copies, refreshes and
trust.
Checkouts
| Command | Purpose |
|---|---|
synck repository checkout [DIRECTORY] --author AUTHOR [--include PATH ...] |
Write files and folders to disk and enable editing, as an independent local copy |
synck repository checkout-selection [DIRECTORY] --include PATH ... |
Replace the set of paths on disk |
synck repository checkout-selection [DIRECTORY] --all |
Put every file and folder on disk |
--include paths are literal, case-sensitive and relative to the repository
root, with / as the separator. Guide: Editing files in a complete
repository.
Writing after the source is retired
| Command | Purpose |
|---|---|
synck repository activate [DIRECTORY] --author AUTHOR --source-retired |
Make this copy the writer that succeeds a retired source |
synck repository create-file NAME SOURCE_FILE [--parent FOLDER_ID] [--path DIRECTORY] |
Create a file from a local file’s bytes |
synck repository save-file FILE_ID SOURCE_FILE [--path DIRECTORY] |
Record new content for an existing file |
synck repository finalize [DIRECTORY] |
Complete an accepted write that reported it needs recovery |
create-chat and append-chat also work here. Guide: Taking over as the
writer.