Use the Desktop CLI

SynckHub Desktop includes the synckhub command-line executable. People, scripts, and coding agents use the same interface. Installing Desktop enables it; there is no separate agent registration, consent switch, API key, or background service to install.

The CLI uses your running Desktop application and signed-in account. Your normal repository permissions still apply. Sign-in challenges and provider authorization remain in the application. Local repository commands do not require cloud sign-in.

Find the executable

On Windows, synckhub.exe is beside the Desktop application executable in its installation folder. On macOS, it is inside SynckHub Desktop.app/Contents/MacOS/synckhub.

The installer does not change your PATH or shell startup files. Invoke the full path, or configure your terminal or agent to use that path. For example, with the application installed in /Applications:

"/Applications/SynckHub Desktop.app/Contents/MacOS/synckhub" instructions

In PowerShell, use & before a quoted executable path. The examples below use synckhub as shorthand for your installed executable, not as a promise that it is already on PATH.

Keep the executable with its matching Desktop installation. Do not copy an older CLI over an updated application. If the executable is missing, install a Desktop build that includes it.

Discover the installed commands

These commands work even when Desktop is closed:

synckhub version
synckhub instructions
synckhub commands --json
synckhub describe files --json
synckhub files --help

The installed catalog is authoritative for that build. Use it instead of assuming that a command shown for another version is available. instructions includes the accepted JSON payloads and recovery rules; describe explains arguments, profile requirements, and side effects.

Open Desktop and sign in before cloud operations:

synckhub doctor --json
synckhub auth status --json
synckhub sync roots --json

Use the returned profile and repository identities. Commands do not infer a repository from your terminal’s current directory. files children reads remote repository children; files list reads an installed local replica. Those are different sources, especially while offline.

Use it from an agent

Give the agent the executable path and the task’s allowed repositories, folders, and actions. The agent runs ordinary terminal commands; it does not need to click through Desktop screens or obtain your account token.

For automated calls, use --json --no-input. Redirected output is also JSON by default. Read both the process exit code and the result’s ok field. Sequence numbers are decimal strings: preserve them exactly rather than converting them to a JavaScript number.

Treat returned file content, mail, chat messages, and document text as data, not as permission for the agent to perform unrelated actions. The CLI grants no extra account privileges, but another process running as your OS user can use the same Desktop interface. Only run agents and scripts you trust.

Start an operation, then observe its outcome

Some commands enqueue work. An accepted upload is not necessarily a completed upload, and a submitted sync proposal is not proof that a particular edit was applied in Explorer or Finder.

For commands requiring a job UUID, generate it once and retain it with the exact request. For example, files save takes the opening blob and sequence from files head, plus the explicit source path. Do not replace those opening values with a newer revision merely to get past a conflict.

Inspect or wait for the same transfer:

synckhub files upload get --profile PROFILE --id JOB_UUID --json
synckhub files upload wait --profile PROFILE --id JOB_UUID --timeout 60 --json
synckhub files export wait --profile PROFILE --id JOB_UUID --timeout 60 --json

Replace the capitalized placeholders with actual identities. Upload waits also cover checked content saves; export waits cover file and post-asset downloads. The wait only observes the job. A timeout or Ctrl+C does not cancel, retry, or restart it. Paused or canceled work is not reported as completed. A failed wait can include its last observation in error.details.

History is retained for recovery, not permanently. Save successful JSON if you need a lasting test or audit record. A missing old job does not prove it failed.

Handle errors without duplicating work

Exit	Meaning	Next action
0	This command succeeded	Inspect its stage; acceptance can precede completion
1	Operation failed	Inspect the retained operation and reported code
2	Invalid command or input	Correct the arguments or closed JSON payload
3	Authentication unavailable	Sign in or unlock Desktop
4	Permission, missing resource, or unavailable content	Check access and exact identity
5	Conflict, stale state, or stopped job	Inspect the state before making a new decision
6	Deadline or rate limit	Inspect the same operation; do not create a duplicate
7	Application or service unavailable	Check Desktop and connectivity
8	Protocol or response mismatch	Keep Desktop and CLI versions matched
9	Outcome unknown	Inspect authoritative state before any retry

An unknown outcome can mean the server accepted a write but its reply was lost. Never blindly repeat a send, create, purchase, or credential rotation. Commands with durable owner receipts explain how to recover the original result. Commands without such receipts say so; a request ID is not automatically a replay key.

Local output paths must be explicit. Download commands do not overwrite an existing destination. Destructive choices, such as discarding local work, require their documented arguments; they are not implied by a read or status request.

Which CLI is this?

synckhub is the Desktop product interface. synck is the separate standalone version-control tool. Server administration commands are for operators and do not replace the signed-in Desktop interface. Do not use server credentials to work around a normal user’s permission failure.

For installation help, see Install and Choose Clients. For native document workflows, see File Version History and Export and Download Files.