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. Every command accepts --json,
before or after the command name, as in synck --json status or
synck status --json. 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 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, and no size limit on a commit. init
and commit rename files and folders whose names other systems cannot store,
and report each rename. 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.
Clones and alternatives
| Command | Purpose |
|---|---|
synck clone ORIGIN NEW_DIRECTORY [--include PATH ...] [--author AUTHOR] [--hold] |
Make another working tree of a repository on this machine |
synck pull [--include PATH ...] |
Bring in commits made from other working trees, keeping local changes |
synck resolve PATH ... |
Mark files that a pull merged with conflicts as resolved |
synck push |
Send a held clone’s commits to its origin, after pulling |
synck duplicate SOURCE DESTINATION [-m MESSAGE] |
Copy a committed file or folder as an alternative in the same history |
synck adopt ALTERNATIVE ORIGINAL [-m MESSAGE] |
Make a file or folder match an alternative of it, keeping its history |
commit, revert, mv, recover and version restore pull first. The
origin must be on a local disk. Guide: Clones and
alternatives.
Reservations
| Command | Purpose |
|---|---|
synck lock acquire PATH ... --owner LABEL [--ttl SECONDS] |
Reserve paths, including new ones, and print a token |
synck lock renew TOKEN |
Extend an unexpired reservation |
synck lock release TOKEN |
Release that token’s reservations |
synck lock list |
List reservations, including expired ones |
synck lock break PATH ... |
Remove reservations that overlap these paths, after checking the work they protected |
A commit that touches a reserved path, from any working tree of the
repository, needs the token: pass it with --lock-token TOKEN. --ttl
defaults to 600 seconds. Reservations are meant for tools and agents that
work side by side.
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 [REVISION] |
Return the whole working tree to the latest commit, or write an earlier commit’s tree. 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] [--limit COUNT] [--after CURSOR] [--through N] [--path DIRECTORY] |
List live tree items at the top level or in a folder |
synck item list --records [--parent FOLDER] [--limit COUNT] [--after CURSOR] [--path DIRECTORY] |
List live records: all of them, or those linked to a folder |
synck item show ITEM [--through N] [--path DIRECTORY] |
Read one item, including messages and refs |
synck item export ITEM NEW_FILE [--through N] [--path DIRECTORY] |
Write a file’s content, or an email’s original message, to a new file |
FOLDER and ITEM are a repository path such as Launch/proposal.txt or an
item ID; a record is always named by its ID. 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 argument. --through takes a sealed
repository sequence, and does not combine with --records. Guide: Reading items
and history.
Email and chats
| Command | Purpose |
|---|---|
synck repository import-email SOURCE [--link FOLDER] [--title TITLE] [--path DIRECTORY] |
Import an .eml or .msg file as an email record; the file itself is left alone |
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 |
An .eml or .msg file in a working tree is committed as an ordinary file.
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] [--path DIRECTORY] |
Create a file from a local file’s bytes |
synck repository save-file FILE SOURCE_FILE [--base-content OBJECT_ID] [--merged-from ITEM@SEQ] [--path DIRECTORY] |
Record new content for an existing file |
synck repository duplicate FILE NAME [--parent FOLDER] [--path DIRECTORY] |
Copy a file’s current content into a new file that records its origin |
synck repository finalize [DIRECTORY] |
Complete an accepted write that reported it needs recovery |
create-file, save-file, duplicate and import-email also take
-m MESSAGE, --author AUTHOR (the repository’s author stays the committer),
--occurred-at TIMESTAMP and --operation-id UUID (a repeat with the same ID
returns the original commit). import-email, create-chat and append-chat
also work here. Guide: Taking over as the
writer.