# VaultLink Local CLI

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

## Installation

### Docker (Recommended)

```bash
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

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

### From Source

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

## Usage

```bash
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 |
|--------|---------|-------------|
| `--sync-concurrency <number>` | `1` | Concurrent sync operations |
| `--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 |
| `-h, --help` | - | Show help |
| `-V, --version` | - | Show version |

### Auto-Ignored Patterns

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

### Examples

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

With ignore patterns:
```bash
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:
```bash
vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default \
  --log-level DEBUG
```

## Docker Deployment

### Docker Run

```bash
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

```yaml
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

```bash
# 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:

```yaml
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:
```bash
npm run build
# or from the parent folder, run
docker build -f local-client-cli/Dockerfile  .
```

Test:
```bash
npm test
```

Docker build:
```bash
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