hsync-cli

Premium, zero-dependency cross-device file synchronization and storage manager terminal client.

hsync-cli is a powerful, lightweight command-line companion for File Sync V2. It allows you to manage buckets, transfer files, and orchestrate automated, real-time bidirectional synchronization directly from your terminal.

🚀 Installation

Install the package globally via your preferred Node package manager:

npm install -g hsync-cli

Note: Once installed, the hsync command will be globally symlinked to your shell environment.

🛠️ Setup & Authentication

Before running synchronization tasks, configure the CLI to target your Express API server and authenticate.

1. Set API Server Target

Specify the URL of the running File Sync V2 API server:

hsync config set-server http://localhost:3000

2. Login & Authenticate

Log in securely to generate and download your persistent personal API key (X-API-Key):

hsync login

Note: You can skip interactive prompts in script/headless environments by passing a pre-generated API key directly:

hsync login --api-key hmd_xxxxxxxxxxxxxxxxxxxx

3. Check Connection

Verify your authenticated session details:

hsync me

4. Logout

Remove credentials and invalidate the active API key session locally:

hsync logout

📁 Managing Storage Buckets

Storage buckets are logical sandboxes backed by pluggable providers (Local folders or Amazon S3 buckets).

List Buckets

See all buckets registered under your account:

hsync bucket list

Create a Bucket

Register a new storage sandbox:

# Create a Local folder provider bucket
hsync bucket create "My Projects" my-projects --provider local --rootPath /data/my-projects

# Create an Amazon S3 provider bucket
hsync bucket create "Cloud Backups" backups --provider s3 --bucket my-aws-s3-bucket-name

Delete a Bucket

Permanently destroy a storage bucket (this also wipes files inside):

hsync bucket delete my-projects

⚡ Direct File Transfers (Push & Pull)

You can run immediate, one-off file or folder transfers without setting up persistent schedules.

Push (Upload to Server)

Upload a local folder or file to a specific remote bucket target (e.g. bucket-slug:optional-remote-path):

hsync push ./my-local-code projects-bucket:active-source

Tip: Skip conflict resolution prompts and force overwrites using -y or --yes:

hsync push ./my-local-code projects-bucket:active-source --yes

Pull (Download to Machine)

Download a folder or file from a remote bucket directly to your local machine:

hsync pull projects-bucket:active-source ./downloaded-code

🔄 Automated Folder Synchronization

The sync engine uses local SQLite trackers to orchestrate continuous synchronization cycles, keeping folders on multiple devices automatically in sync with the remote server.

1. Register a Sync Profile

Define a persistent local-to-remote folder synchronization job:

hsync sync add /path/to/local/dir bucket-slug:remote-path \
  --name project-sync \
  --direction bidirectional \
  --strategy newer-wins \
  --interval 10

Sync Config Flags:

• -n, --name <jobName>: A unique name identifier for your job.
• -d, --direction <push|pull|bidirectional>: Sync direction format.
• -s, --strategy <local-wins|server-wins|newer-wins>: Rules on resolving file modifications conflicts.
• -i, --interval <seconds>: Frequency of the background scan cycle (default: 10 seconds).
• --no-conflict-copy: Disable saving conflict backup files (filename.conflict-YYYY-MM-DD.ext).

2. List Registered Sync Jobs

List all synchronization jobs configured on your machine:

hsync sync list

3. Remove a Sync Job

Stop tracking a registered sync job:

hsync sync remove project-sync

4. Start the Synchronization Scheduler

Launch the active sync loop to scan and synchronize folders automatically in the background:

# Start all registered sync jobs
hsync sync start

# Start a specific sync job by name
hsync sync start project-sync

🛡️ License

MIT License. Designed with antigravity by the Advanced Agentic Coding team.