CLI Documentation

Command-line interface guide

Synclet comes with a companion CLI tool that you can deploy to your server or run on your macOS machine. The CLI provides powerful automation capabilities for syncing your configuration files across your infrastructure.

Read the CLI setup guide →

Installation

Install the Synclet CLI globally via npm:

npm install -g synclet

Upgrading from ConfigMesh? The CLI used to ship as the configmesh package and binary. As of 2.0.0 it is synclet:

npm uninstall -g configmesh
npm install -g synclet

Nothing else has to change. Your existing ~/.config/configmesh directory is still picked up, the CONFIGMESH_* environment variables still work, and --configmesh-url, --configmesh-token and --backend configmesh are still accepted as deprecated aliases.

Authentication

Before using Synclet, you need to authenticate:

synclet auth login

This command will open your browser to complete the login process.

Configuration

Set up a new configuration or pull existing configurations from remote:

Initialize New Configuration

synclet config init

Creates a new configuration bundle in the current directory.

Pull Remote Configurations

synclet config pull

Downloads and syncs your configuration bundles from Synclet.

Working with Plans

Plans define which files and directories to sync. Execute a plan to sync your configurations:

synclet plan --passphrase xxxx

This command will execute the plan defined in your configuration bundle, syncing the specified files and directories. The passphrase is required to decrypt your encrypted configuration files.

Sync Command

Manually trigger a sync of your configurations:

synclet sync --passphrase xxxx

This will upload any local changes and download any remote changes to your configuration files. The passphrase is required to encrypt and decrypt your files.

Common Workflow

A typical workflow looks like this:

Login:
```
synclet auth login
```
Initialize or pull configuration:
```
synclet config init
```
or
```
synclet config pull
```
Execute plan:
```
synclet plan --passphrase xxxx
```
Sync changes:
```
synclet sync --passphrase xxxx
```

Configuration File

Synclet uses a YAML configuration file located at ~/.config/synclet/config.yaml. This file defines bundles that specify which files and directories to sync.

Example Configuration

version: 1
bundles:
  - id: fish
    description: fish shell configuration
    logical_root: $HOME/.config/fish
    includes:
      - "**/*.fish"
    excludes:
      - "*.DS_Store"

  - id: ghostty
    description: Ghostty terminal
    logical_root: $HOME/.config/ghostty
    includes:
      - config
    excludes:
      - "*.DS_Store"

  - id: xcode
    description: Xcode preferences
    logical_root: $HOME/Library
    includes:
      - Developer/Xcode/UserData/CodeSnippets/**
      - Developer/Xcode/UserData/KeyBindings/**
      - Preferences/com.apple.dt.Xcode.plist
    excludes:
      - "*.DS_Store"

Key fields:

id: Unique identifier for the bundle
description: Human-readable description
logical_root: Base directory (supports $HOME variable)
includes: File patterns to sync (supports globs like ** and *)
excludes: File patterns to ignore