vault-link/frontend/local-client-cli

VaultLink Local CLI

Standalone CLI for syncing VaultLink vaults to local filesystem with real-time bidirectional sync and file watching.

Installation

Docker (Recommended)

docker pull ghcr.io/schmelczer/vault-link-cli:latest

docker run -v /path/to/vault:/vault \
  ghcr.io/schmelczer/vault-link-cli:latest \
  -l /vault \
  -r wss://sync.example.com \
  -t your-auth-token \
  -v default

npm

npm install -g @schmelczer/local-client-cli
vaultlink --help

From Source

cd frontend/local-client-cli
npm install
npm run build
node dist/cli.js --help

Usage

vaultlink \
  --local-path ./vault \
  --remote-uri wss://sync.example.com \
  --token your-auth-token \
  --vault-name default

Options

Required

Option	Description
-l, --local-path <path>	Local directory to sync
-r, --remote-uri <uri>	Remote server WebSocket URI (ws:// or wss://)
-t, --token <token>	Authentication token
-v, --vault-name <name>	Vault name on server

Optional

Option	Default	Description
--max-file-size-mb <number>	10	Maximum file size in MB
--ignore-pattern <pattern>	-	Glob pattern to ignore (repeatable)
--websocket-retry-interval-ms <ms>	3500	WebSocket reconnection interval
--log-level <level>	INFO	Log level: DEBUG, INFO, WARNING, ERROR
--line-endings <mode>	auto	Line ending style: auto, lf, crlf
-q, --quiet	-	Suppress startup banner for non-interactive use
-h, --help	-	Show help
-V, --version	-	Show version

Auto-Ignored Patterns

• .vaultlink/** - Internal sync metadata
• .git/** - Git repository files

Examples

Basic usage:

vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default

With ignore patterns:

vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default \
  --ignore-pattern "**/*.tmp" \
  --ignore-pattern ".DS_Store" \
  --ignore-pattern "node_modules/**"

With debug logging and quiet startup:

vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default \
  --log-level DEBUG --quiet

Force LF line endings (useful for cross-platform vaults):

vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default \
  --line-endings lf

Docker Deployment

Docker Run

docker run -d \
  --name vaultlink-sync \
  --restart unless-stopped \
  -v $(pwd)/vault:/vault \
  ghcr.io/schmelczer/vault-link-cli:latest \
  -l /vault \
  -r wss://your-server.com \
  -t your-token \
  -v default

Docker Compose

services:
  vaultlink-cli:
    image: ghcr.io/schmelczer/vault-link-cli:latest
    volumes:
      - ./vault:/vault
    command:
      - "-l"
      - "/vault"
      - "-r"
      - "wss://sync.example.com"
      - "-t"
      - "your-token"
      - "-v"
      - "default"
    restart: unless-stopped

Health Monitoring

The Docker container includes a built-in healthcheck that monitors the WebSocket connection to the server.

Healthcheck Configuration

• Interval: 30 seconds
• Timeout: 10 seconds
• Start period: 30 seconds (grace period for initial connection)
• Retries: 3 failed checks before marking unhealthy

How It Works

The CLI writes connection status to /tmp/vaultlink-health.json every 10 seconds and whenever the WebSocket connection status changes. The healthcheck script verifies:

1. The health file exists
2. The status is recent (updated within last 30 seconds)
3. The WebSocket connection is active

Checking Container Health

# View health status
docker ps

# View detailed health check logs
docker inspect --format='{{json .State.Health}}' vaultlink-sync | jq

Custom Healthcheck

To override the default healthcheck in docker-compose.yml:

services:
  vaultlink-cli:
    image: ghcr.io/schmelczer/vault-link-cli:latest
    healthcheck:
      test: ["CMD", "node", "/app/healthcheck.js"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 20s

Development

Build:

npm run build
# or from the parent folder, run
docker build -f local-client-cli/Dockerfile  .

Test:

npm test

Docker build:

cd frontend
docker build -f local-client-cli/Dockerfile -t vault-link-cli:test .

How It Works

1. Creates .vaultlink directory for sync metadata
2. Performs initial sync of local files to server
3. Watches filesystem for changes using Node's fs.watch
4. Syncs changes bidirectionally in real-time
5. Handles graceful shutdown on SIGINT/SIGTERM

License

MIT