FileSync CLI

A command-line interface tool for synchronizing files between local and remote servers.

Installation

Local Development

npm install
npm link

From NPM (when published)

npm install -g filesync-cli

Usage

Login

Login to the file sync server:

filesync login -u <username> -p <password>

Example:

filesync login -u admin -p admin123

Check Status

View your login status and user information:

filesync status

Push Files

Upload files or folders from local to server with parallel uploads and progress tracking:

filesync push <local-path> <server-path> [options]

Examples:

# Upload a single file
filesync push ./document.pdf /documents/

# Upload an entire folder (default 4 concurrent uploads)
filesync push ./my-folder /backup/my-folder

# Upload with 8 concurrent connections
filesync push ./my-folder /backup/my-folder -c 8

# Overwrite existing files
filesync push ./file.txt /files/ -o

# Combine options
filesync push ./large-folder /server/ -o -c 10

Options:

• -o, --overwrite - Overwrite existing files on the server
• -c, --concurrent <number> - Number of concurrent uploads (default: 4)

Features:

• Individual progress bar for each uploading file showing:
  • Encoding progress (reading and encoding file)
  • Upload progress
  • File size
  • File name with status
• Smart display: completed files are automatically removed, showing only active uploads
• Overall progress bar at the bottom showing completed/total files count
• Parallel uploads (up to specified concurrent limit)
• Clean interface: no clutter from completed files
• Failed files show error message briefly (1 second) before removal
• Final summary of successful and failed files

Pull Files

Download files or folders from server to local with parallel downloads and progress tracking:

filesync pull <server-path> <local-path> [options]

Examples:

# Download a single file
filesync pull /documents/report.pdf ./downloads/report.pdf

# Download an entire folder (default 4 concurrent downloads)
filesync pull /backup/my-folder ./restored-folder/

# Download with 8 concurrent connections
filesync pull /backup/my-folder ./restored-folder/ -c 8

# Overwrite existing local files
filesync pull /files/config.json ./config.json -o

# Combine options
filesync pull /large-folder ./local/ -o -c 10

Options:

• -o, --overwrite - Overwrite existing local files
• -c, --concurrent <number> - Number of concurrent downloads (default: 4)

Features:

• Individual progress bar for each downloading file showing:
  • Download percentage (0-100%)
  • Current/total file size (e.g., 1.2 MB / 5.4 MB)
  • File name with status (yellow while downloading)
• Smart display: completed files are automatically removed, showing only active downloads
• Overall progress bar at the bottom showing completed/total files count
• Parallel downloads (up to specified concurrent limit)
• Clean interface: no clutter from completed files
• Failed files show error message briefly (1 second) before removal
• Final summary of successful, failed, and skipped files

Logout

Logout from the file sync server:

filesync logout

Configuration

Manage CLI configuration settings:

# List all configuration
filesync config --list
filesync config

# Set server URL
filesync config serverUrl=https://myserver.com
filesync config serverUrl=http://localhost:8080

# Multiple values at once
filesync config serverUrl=https://myserver.com

Configuration Options:

• serverUrl - The file sync server URL (default: http://localhost:3000)

Configuration Priority:

1. Saved config file (~/.filesync/config.json)
2. Environment variable (FILESYNC_SERVER_URL)
3. Default value (http://localhost:3000)

Background Sync (Coming Soon)

Configure the app to run on system startup for automatic file synchronization:

filesync startup --enable   # Enable background sync
filesync startup --disable  # Disable background sync
filesync startup --status   # Check status

Configuration

Configuration and authentication tokens are stored in:

• Linux/Mac: ~/.filesync/config.json
• Windows: %USERPROFILE%\.filesync\config.json

Server Configuration

By default, the CLI connects to http://localhost:3000. You can change the server URL in three ways:

1. Using the config command (Recommended):

filesync config serverUrl=https://your-server.com

2. Using environment variable:

export FILESYNC_SERVER_URL=https://your-server.com
filesync login -u user -p pass

3. Editing config.js directly:

export const config = {
  serverUrl: 'https://your-server.com',
};

Priority: Config file > Environment variable > Default value

Features

• ✅ User authentication (login/logout)
• ✅ Status checking
• ✅ Push files/folders to server with parallel uploads
• ✅ Pull files/folders from server with parallel downloads
• ✅ Configurable concurrency for both push and pull operations
• ✅ Real-time progress bars with per-file tracking
• ✅ Smart display: only show active transfers (completed files auto-removed)
• ✅ Recursive folder operations
• ✅ Overwrite protection with -o flag
• ✅ Configuration management (server URL)
• ⏳ Background sync service (coming soon)
• ⏳ Conflict resolution (coming soon)

Development

Project Structure

client-cli/
├── index.js           # Main CLI entry point
├── api-client.js      # API client for server communication
├── config-manager.js  # Configuration and credential management
├── file-utils.js      # Local file system utilities
├── config.js          # Server configuration
├── package.json       # Package metadata
└── README.md          # Documentation

API Integration

The CLI uses the file-based API structure from the server:

• Endpoint: POST /api/fn?fn=<function-path>
• Authentication: JWT Bearer token in Authorization header
• Request format: { "args": { ... } }

Publishing to NPM

1. Update version in package.json
2. Login to NPM: npm login
3. Publish: npm publish

License

ISC