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.