How to set up the Synclet (ex ConfigMesh) CLI - Guides

Synclet (ex ConfigMesh) ships with a companion CLI you can run on macOS or deploy to a server.

This guide walks through a clean first setup: install, authenticate, initialize (or pull), then do a safe dry run (plan) before applying changes (sync).

Install

Install the Synclet (ex ConfigMesh) CLI globally via npm:

npm install -g synclet

This downloads a prebuilt binary at install time.

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.

Authenticate

synclet auth login

This opens a browser to complete the login flow.

Create Or Pull A Configuration

You have two ways to start.

Option A: Initialize a new config

synclet config init

This creates a new configuration bundle in the current directory.

Option B: Pull an existing config

synclet config pull

This downloads and syncs your configuration bundles from Synclet (ex ConfigMesh).

Planning vs Syncing

plan is a dry run: it tells you what Synclet (ex ConfigMesh) would do.
sync applies that plan: it uploads/downloads encrypted changes.

If you are changing rules or expanding what you sync, run plan first until the output matches your intent.

Run Your First Plan

synclet plan --passphrase xxxx

The passphrase is required to decrypt your encrypted configuration files.

Example output:

❯ synclet plan --passphrase '********'
planning bundle: helix
planning bundle: .factory
planning bundle: aria2c
planning bundle: crush
planning bundle: fish
planning bundle: neovim
planning bundle: opencode
planning bundle: demo
planning bundle: codex
crush   local->remote   crush.json              content change
codex   local->remote   rules/default.rules     content change
codex   remote->local   config.toml             content change

Apply With Sync

synclet sync --passphrase xxxx

This uploads any local changes and downloads any remote changes.

Example output (syncing a single bundle):

❯ synclet sync --passphrase '********' --bundle crush
planning bundle: crush
crush   local->remote   crush.json      content change
uploading crush.json (11062 bytes)
Applied 1 action(s) for bundle crush

Where The Config Lives

Synclet (ex ConfigMesh) uses a YAML configuration file at:

~/.config/synclet/config.yaml

That file defines bundles (what to sync) and the include/exclude rules for each bundle.

Example `config.yaml`

This is the shape Synclet (ex ConfigMesh) expects (simplified):

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

Bundle Fields

id: short stable identifier (used in logs/UI).
description: human-readable label.
logical_root: base directory for the bundle. $HOME is supported.
includes: glob patterns to include (paths are relative to logical_root).
excludes: glob patterns to exclude (same matching rules as includes).

More Realistic Patterns

Sync an entire folder recursively:

  - id: fish
    description: fish
    logical_root: $HOME/.config/fish
    includes:
      - "**/*.fish"
    excludes:
      - "*.DS_Store"

Sync a project-style folder but only specific subtrees and files:

  - id: factory
    description: Factory
    logical_root: $HOME/.factory
    includes:
      - skills/**
      - commands/**
      - config.json
      - settings.json
    excludes:
      - "*.DS_Store"

When you edit rules, run synclet plan --passphrase ... to verify the match set, then synclet sync --passphrase ... to apply it.