← Back to Guides

GUIDE

How to set up the ConfigMesh CLI

Install the CLI, authenticate, initialize or pull a config, then plan and sync.

February 07, 2026Tags: clisetupsync

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 ConfigMesh CLI globally via npm:

npm install -g configmesh

This downloads a prebuilt binary at install time.

Authenticate

Log in from the CLI:

configmesh 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

configmesh config init

This creates a new configuration bundle in the current directory.

Option B: Pull an existing config

configmesh config pull

This downloads and syncs your configuration bundles from ConfigMesh.

Planning vs Syncing

  • plan is a dry run: it tells you what 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

configmesh plan --passphrase xxxx

The passphrase is required to decrypt your encrypted configuration files.

Example output:

❯ configmesh 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

configmesh sync --passphrase xxxx

This uploads any local changes and downloads any remote changes.

Example output (syncing a single bundle):

❯ configmesh 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

ConfigMesh uses a YAML configuration file at:

~/.config/configmesh/config.yaml

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

Example config.yaml

This is the shape 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 configmesh plan --passphrase ... to verify the match set, then configmesh sync --passphrase ... to apply it.