SyncEnv CLI

CLI for SyncEnv - Secure environment variable synchronization.

Installation

Via npm (Recommended)

npm install -g @uagents/syncenv-cli

Via pnpm

pnpm add -g @uagents/syncenv-cli

Via curl (Standalone Binary)

curl -sL https://syncenv-files.uagents.app/cli/install.sh | bash

With custom install directory:

curl -sL https://syncenv-files.uagents.app/cli/install.sh | INSTALL_DIR=~/.local/bin bash

Quick Start

One-Command Setup (Recommended)

syncenv setup

The setup wizard will:

1. Check if you're authenticated (prompt for login/signup if not)
2. Guide you through account creation if needed
3. Automatically generate your encryption keys
4. Save keys to server and cache locally

Then Initialize Your Project

cd ~/my-project
syncenv init
syncenv env push

Commands

Setup

• syncenv setup - First-time setup wizard (login + encryption keys)
  • --debug - Enable debug mode with verbose logging

Authentication

• syncenv auth login - Login to your account
  • --debug - Enable debug mode
• syncenv auth logout - Logout and clear session
• syncenv auth status - Check authentication status
• syncenv auth signup - Open browser to create account

Project Management

• syncenv init - Initialize project configuration (creates .syncenvrc and optionally creates project on server)

  • -y, --yes - Skip prompts and use defaults
  • --debug - Enable debug mode

  Note: Environments are created automatically on first push. Run syncenv env push -e <env> to create and upload to an environment.

• syncenv project list - List all projects

  • -s, --search <query> - Search projects by name
  • -l, --limit <number> - Number of projects to show (default: 20)
  • --cursor <cursor> - Cursor for pagination
  • --debug - Enable debug mode

• syncenv project create [name] - Create a new project

  • -d, --description <description> - Project description
  • --debug - Enable debug mode

• syncenv project get <identifier> - Get project details. Identifier can be project ID (proj_xxx) or project name

  • --debug - Enable debug mode

• syncenv project delete <identifier> - Delete a project. Identifier can be project ID (proj_xxx) or project name

  • -f, --force - Skip confirmation
  • --debug - Enable debug mode

• syncenv project use <identifier> - Set default project for current directory (updates .syncenvrc). Identifier can be project ID (proj_xxx) or project name

  • --debug - Enable debug mode

Configuration Management

• syncenv config list - List all configuration values
  • --debug - Enable debug mode
• syncenv config get <key> - Get a configuration value
  • --debug - Enable debug mode
• syncenv config set <key> [value] - Set a configuration value
  • --debug - Enable debug mode
• syncenv config delete <key> - Delete a configuration value (reset to default)
  • --debug - Enable debug mode
• syncenv config reset - Reset all configuration to defaults
  • -f, --force - Skip confirmation
  • --debug - Enable debug mode
• syncenv config path - Show configuration file path

Environment Variables

• syncenv env push - Push .env file to server
  • -p, --project <id> - Project ID (or use .syncenvrc project.id)
  • -e, --env <name> - Environment name (default: dev)
  • -f, --file <path> - File path
  • -m, --message <message> - Change description
  • --force - Force push without conflict check
  • --strategy <strategy> - Merge strategy on conflict
  • --debug - Enable debug mode
• syncenv env pull - Pull .env file from server
  • -p, --project <id> - Project ID
  • -e, --env <name> - Environment name
  • -f, --file <path> - Output file path
  • -v, --version <number> - Specific version to pull
  • -m, --merge - Merge with existing file
  • --debug - Enable debug mode
• syncenv env sync - Smart sync (pull + merge + push)
  • --strategy <strategy> - Conflict resolution: interactive, local-wins, remote-wins, fail-on-conflict
  • --dry-run - Preview changes without applying
  • -y, --yes - Skip confirmation prompts
  • --debug - Enable debug mode
• syncenv env history - Show version history
  • -l, --limit <number> - Number of versions to show
  • --debug - Enable debug mode
• syncenv env diff <v1> <v2> - Compare two versions
  • --debug - Enable debug mode
• syncenv env rollback <version> - Rollback to a specific version
  • -f, --force - Skip confirmation
  • --debug - Enable debug mode

User Keys (Encryption Management)

• syncenv user-keys setup - Initialize encryption keys (first time)
  • --debug - Enable debug mode
• syncenv user-keys unlock - Unlock encryption keys for session
  • --no-remember - Do not store in keychain
  • --debug - Enable debug mode
• syncenv user-keys lock - Lock keys from memory
  • --forget - Also remove from keychain
  • --debug - Enable debug mode
• syncenv user-keys status - Check encryption key status
  • --debug - Enable debug mode
• syncenv user-keys rotate - Re-encrypt keys with new password
  • --debug - Enable debug mode

Device Management

• syncenv device list - List all devices
  • --debug - Enable debug mode
• syncenv device authorize <id> - Authorize a pending device
• syncenv device revoke <id> - Revoke a device
• syncenv device remove <id> - Remove a device
• syncenv device current - Show current device info

Diagnostics

• syncenv doctor - Diagnose configuration and connectivity issues
  • --debug - Enable debug mode

Smart Merge

When pushing or syncing, if remote has been modified since your last pull, the CLI automatically performs a three-way merge:

1. Detect conflicts - Compare your local changes with remote changes
2. Auto-merge - Non-conflicting changes are merged automatically
3. Interactive resolution - Conflicts are presented with options:
   • [l] Use local value
   • [r] Use remote value
   • [b] Keep both values
   • [e] Edit custom value
   • [s] Skip and keep conflict markers

Merge Strategies

# Interactive (default) - prompt for each conflict
syncenv env sync

# Local wins - always use your changes
syncenv env sync --strategy=local-wins

# Remote wins - always use remote changes
syncenv env sync --strategy=remote-wins

# Fail on conflict - exit if conflicts exist
syncenv env push --strategy=fail-on-conflict

Configuration

CLI Config

Stored in OS-specific config directory:

• macOS: ~/Library/Application Support/syncenv/
• Linux: ~/.config/syncenv/
• Windows: %APPDATA%/syncenv/

Contains:

• apiUrl - API base URL (default: https://syncenv-api.uagents.app)
• autoLockMinutes - Auto-lock timeout in minutes (0 to disable, default: 30)
• userId - User ID
• userEmail - User email

Project Config (.syncenvrc)

Example:

project:
  name: myapp
  id: proj_xxx

defaults:
  environment: dev
  pushOnChange: false
  confirmOverwrite: true

encryption:
  algorithm: AES-256-GCM
  keyDerivation: Argon2id

environments:
  dev:
    file: .env
  staging:
    file: .env.staging
  production:
    file: .env.production
    requireConfirmation: true

Environment Variables

• SYNCENV_API_URL - API base URL (default: https://syncenv-api.uagents.app)
• SYNCENV_DEBUG - Enable debug mode (set to true)
• SYNCENV_VERBOSE - Enable verbose logging

Common Workflows

First-Time Setup

# Install CLI
curl -sL https://syncenv-files.uagents.app/cli/install.sh | bash

# Run setup wizard
syncenv setup

# Initialize your project
cd ~/my-project
syncenv init

# Push your first environment
syncenv env push -m "Initial setup"

Daily Development

# Unlock keys (cached in keychain by default)
syncenv user-keys unlock

# Sync environment (pull + merge + push)
syncenv env sync

# Make changes to .env...

# Push with message
syncenv env push -m "Added Stripe API keys"

# Lock when done (optional on personal machine)
syncenv user-keys lock

Working with Multiple Environments

# Push to specific environment
syncenv env push -e production -m "Database migration config"

# Pull from staging
syncenv env pull -e staging

# Sync with specific strategy
syncenv env sync -e production --strategy=interactive

CI/CD Pipeline

# Non-interactive pull
syncenv env pull -e production -y

# Or with specific strategy
syncenv env sync -e production --strategy=local-wins -y

Troubleshooting

Debug Mode

Most commands support --debug flag:

syncenv setup --debug
syncenv auth login --debug
syncenv env push --debug

Common Issues

"Not authenticated" error:

syncenv auth login
# or
syncenv setup

"Encryption keys are locked" error:

syncenv user-keys unlock

"No project specified" error:

# Option 1: Set project in .syncenvrc (supports ID or name)
syncenv project use my-project-name
# or
syncenv project use proj_xxx

# Option 2: Use --project flag
syncenv env push --project proj_xxx

Merge conflicts:

# Interactive resolution
syncenv env sync --strategy=interactive

# Or force local changes
syncenv env push --force

Security

• All encryption/decryption happens locally on your device
• Your login password never leaves your device
• Data Encryption Keys (DEK) are encrypted with your Key Encryption Key (KEK)
• KEK is derived from your login password using PBKDF2
• Server only stores encrypted data and cannot decrypt your environment variables
• Keys are cached in system keychain by default (use --no-remember to disable)
• Always run syncenv user-keys lock when done on shared machines

License

MIT