CLI Documentation

Command-line interface guide

ConfigMesh 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.

Installation

Install the ConfigMesh CLI globally via npm:

npm install -g configmesh

Authentication

Before using ConfigMesh, you need to authenticate:

configmesh 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

configmesh config init

Creates a new configuration bundle in the current directory.

Pull Remote Configurations

configmesh config pull

Downloads and syncs your configuration bundles from ConfigMesh.

Working with Plans

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

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

configmesh 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:
```
configmesh auth login
```

Initialize or pull configuration:

configmesh config init

configmesh config pull

Execute plan:
```
configmesh plan --passphrase xxxx
```
Sync changes:
```
configmesh sync --passphrase xxxx
```

Configuration File

ConfigMesh uses a YAML configuration file located at ~/.config/configmesh/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