Usage & Features

Cloud Sync

Chain Hub uses Git behind the scenes to securely synchronize your entire instruction library, rule presets, agents, and workflows across multiple devices.

Unlike typical cloud folders (like Dropbox, iCloud, or Syncthing) which can corrupt git history, lock files, or propagate accidental deletions, Chain Hub’s synchronization model is built on standard Git branching and conflict resolution.

How it works

When you initialize sync, the CLI turns your active hub path (~/chain-hub) into a local Git repository and binds it to a private remote repository of your choice.

The Synchronized Architecture:



    

  • Local Repositories: Your hub directory on each machine (e.g. Laptop A and Laptop B) acts as a local Git repository tracking your rules and assets.
    • 

  • Private Central Remote: A central, private repository (hosted on GitHub, GitLab, etc.) securely stores the revision history.
    • 

  • Rebase Integration: Devices synchronize by pushing local updates and pulling/rebasing upstream commits from the remote repository.
    • 



During a sync event:


    

  1. The CLI stages and commits any new or changed assets in your hub.
    2. 

  2. It fetches upstream changes from your remote.
    3. 

  3. It performs a fast-forward merge or rebase to integrate changes from other devices.
    4. 

  4. It pushes your commits to the remote.
    5. 





How to get started


    

  1. Create a remote repository: Create a new private repository on GitHub, GitLab, or any Git host.
    2. 

  2. Authenticate your environment: Ensure your terminal shell is authorized to access the remote (via SSH keys, gh auth login, or standard HTTP tokens).
    3. 

  3. Initialize synchronization:

    chain sync init <your-git-repo-url>
    

    4. 

  4. Trigger a sync:
Run the sync command whenever you want to pull updates or upload changes:

    chain sync
    

    5. 

  5. Check status:
To inspect the branch tracking and connection health:

    chain sync status
    

    6. 





Synchronization Best Practices




[!WARNING]
Do NOT run external file synchronization utilities (like Syncthing, Dropbox, Resilio Sync, or OneDrive) on your active hub directory in parallel with Git sync. Doing so can cause working-tree locks, merge conflicts, and accidental file overrides.




    

  • Private Repositories Only: Your hub contains personal preferences, codebase instructions, and possibly project rules. Always keep your sync repository private.
    • 

  • Run Setup After Sync: If you pulled down changes that added or updated adapter plugins, run chain setup to update your IDE symlinks.
    • 

  • Sync Configuration: Machine-specific paths (like editor config paths in ~/.config/chain-hub/config.json) are not synchronized; they remain completely local to each device.
    •