← Back to Documentation

CLI Guide

The TensorSync CLI provides a powerful command-line interface for synchronizing tensors, managing checkpoints, and monitoring your ML pipelines.

Installation

macOS / Linux

# Install via Homebrew (macOS)
brew install tensorsync/tap/tensorsync

# Or use the install script (Linux/macOS)
curl -sSL https://tensorsync.xyz/install.sh | bash

# Verify installation
tensorsync --version
# Output: TensorSync CLI v2.4.1
    

Windows

# Install via Scoop
scoop bucket add tensorsync https://github.com/tensorsync/scoop-bucket
scoop install tensorsync

# Or download the installer
# https://tensorsync.xyz/downloads/tensorsync-windows-amd64.msi
    

Docker

docker pull tensorsync/cli:latest
docker run --rm tensorsync/cli --version
    

Authentication

Before using TensorSync, authenticate with your API key:

# Interactive login
tensorsync auth login

# Or provide API key directly
tensorsync auth login --token tsk_your_api_key_here

# Check authentication status
tensorsync auth status
    

💡 Tip: Store your API key in ~/.tensorsync/config.json for persistent authentication across sessions.

Core Commands

tensorsync sync

Synchronize tensors between local and remote repositories

Usage

tensorsync sync --repo <repository> [options]

Flags

--repo, -r Repository name (required)

--watch, -w Watch for changes and sync automatically

--compress, -c Enable delta compression (default: true)

--parallel, -p Number of parallel sync streams (default: 4)

--dry-run Show what would be synced without actually syncing

Examples

# Basic sync
tensorsync sync --repo research/imagenet-2024

# Watch mode with compression
tensorsync sync --repo experiments/llama3-finetune --watch --compress

# Dry run to preview changes
tensorsync sync --repo models/vision-transformer --dry-run
        

tensorsync pull

Download specific model checkpoints or tensors

Usage

tensorsync pull --model <model-name> [options]

Flags

--model, -m Model name (required)

--version, -v Specific version (default: latest)

--output, -o Output directory (default: ./models)

--format, -f Output format: safetensors, pytorch, tensorflow (default: safetensors)

Examples

# Pull latest version
tensorsync pull --model llama-3-70b

# Pull specific version in PyTorch format
tensorsync pull --model vision-transformer-base --version v3.2.1 --format pytorch

# Pull to custom directory
tensorsync pull --model bert-large --output /data/models
        

tensorsync telemetry

Stream real-time metrics from training jobs

Usage

tensorsync telemetry --job <job-id> [options]

Flags

--job, -j Job ID (required)

--metrics Comma-separated list of metrics (default: all)

--format Output format: json, csv, table (default: table)

--interval Update interval in seconds (default: 5)

Examples

# Stream all metrics
tensorsync telemetry --job training-job-42

# Stream specific metrics in JSON
tensorsync telemetry --job training-job-42 --metrics loss,grad_norm,gpu_util --format json

# Save to file
tensorsync telemetry --job training-job-42 --format csv > metrics.csv
        

Configuration

Config File Location

TensorSync CLI looks for configuration in the following order:

./.tensorsync/config.json (project-level)
~/.tensorsync/config.json (user-level)
/etc/tensorsync/config.json (system-level)

Example Configuration

{
  "api_endpoint": "https://api.tensorsync.xyz",
  "api_key": "tsk_your_api_key",
  "default_region": "eu-central",
  "compression": {
    "enabled": true,
    "algorithm": "zstd",
    "level": 3
  },
  "sync": {
    "parallel_streams": 4,
    "chunk_size_mb": 64,
    "retry_attempts": 3
  },
  "logging": {
    "level": "info",
    "file": "~/.tensorsync/cli.log"
  }
}
    

Environment Variables

Variable	Description	Default
`TENSORSYNC_API_KEY`	API key for authentication	-
`TENSORSYNC_ENDPOINT`	API endpoint URL	https://api.tensorsync.xyz
`TENSORSYNC_REGION`	Default region for sync operations	auto
`TENSORSYNC_LOG_LEVEL`	Logging level (debug, info, warn, error)	info

Advanced Usage

Custom Sync Policies

Create a .tensorsync/sync-policy.yaml file for advanced sync rules:

# .tensorsync/sync-policy.yaml
version: "2.0"

rules:
  - name: "large-tensors"
    pattern: "**/*.pt"
    min_size_mb: 100
    compression: true
    priority: "high"
    
  - name: "checkpoints"
    pattern: "**/checkpoint-*.safetensors"
    retention_days: 30
    versioning: true
    
  - name: "logs"
    pattern: "**/*.log"
    compression: false
    ttl_hours: 24
    

CI/CD Integration

Example GitHub Actions workflow:

# .github/workflows/sync-models.yml
name: Sync Models
on:
  push:
    paths:
      - 'models/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install TensorSync CLI
        run: curl -sSL https://tensorsync.xyz/install.sh | bash
      
      - name: Authenticate
        run: tensorsync auth login --token ${{ secrets.TENSORSYNC_API_KEY }}
      
      - name: Sync models
        run: tensorsync sync --repo production/models --compress
    

⚠️ Security Note: Never commit API keys to version control. Use environment variables or secret management tools.

Troubleshooting

Common Issues

Authentication Failed

# Check if you're authenticated
tensorsync auth status

# Re-authenticate
tensorsync auth login --token your_new_api_key
    

Connection Timeout

# Check API endpoint
tensorsync config get api_endpoint

# Test connectivity
curl -I https://api.tensorsync.xyz/health
    

Sync Stuck

# Enable debug logging
tensorsync sync --repo my-repo --log-level debug

# Check logs
tail -f ~/.tensorsync/cli.log
    

Getting Help

tensorsync --help - Show all commands
tensorsync <command> --help - Show help for specific command
Full Documentation
Contact Support