CLI Quickstart Guide

Installation

1. Download the latest binary for your platform from keryx.dev
2. Add the binary to your PATH or run it directly

Verify installation:

keryx --version
keryx --help

Commands Overview

S3 Transfers

Configure S3 Credentials

Before using S3 commands, configure your credentials.

# Create a new S3 profile
keryx config \
  --name "My Wasabi" \
  --bucket my-bucket-name \
  --endpoint https://s3.us-east-1.wasabisys.com \
  --region us-east-1 \
  --access-key YOUR_ACCESS_KEY \
  --secret-key YOUR_SECRET_KEY

# View current profile
keryx config

# List all profiles
keryx config --list

# Switch to a different profile
keryx config --use "My Wasabi"

# Rename the active profile
keryx config --name "New Name"

# Delete active profile
keryx config --clean

Config Options:

• --bucket - S3 bucket name
• --endpoint - S3 endpoint URL
• --region - AWS region
• --access-key - AWS access key ID
• --secret-key - AWS secret access key
• --name - Profile name
• --list - List all profiles
• --use <NAME> - Switch to profile by name
• --clean - Delete active profile

S3 credentials are stored securely in your OS keyring (Windows Credential Manager, macOS Keychain, Linux Secret Service).

Provider-Specific Configuration

Different S3-compatible providers have specific requirements:

Wasabi:

keryx config \
  --bucket my-bucket \
  --endpoint https://s3.eu-south-1.wasabisys.com \
  --region eu-south-1 \
  --access-key ... --secret-key ...

• Region must match your bucket's region (e.g., us-east-1, eu-south-1, ap-northeast-1)
• Endpoint must include the region: https://s3.<region>.wasabisys.com

DigitalOcean Spaces:

keryx config \
  --bucket my-bucket \
  --endpoint https://sfo3.digitaloceanspaces.com \
  --region sfo3 \
  --access-key ... --secret-key ...

• Region uses DO's format (e.g., nyc3, sfo3, ams3, sgp1)
• Endpoint must be the base FQDN: https://<region>.digitaloceanspaces.com
• Do NOT include the bucket name in the endpoint

Backblaze B2:

keryx config \
  --bucket my-bucket \
  --endpoint https://s3.us-west-004.backblazeb2.com \
  --region us-west-004 \
  --access-key ... --secret-key ...

AWS S3:

keryx config \
  --bucket my-bucket \
  --endpoint https://s3.us-east-1.amazonaws.com \
  --region us-east-1 \
  --access-key ... --secret-key ...

Cloudflare R2:

keryx config \
  --bucket my-bucket \
  --endpoint https://<account-id>.r2.cloudflarestorage.com \
  --region auto \
  --access-key ... --secret-key ...

Upload Files

# Upload a single file
keryx upload -f ./myfile.zip -k remote/path/myfile.zip

# Upload with explicit S3 flag (optional, S3 is default)
keryx upload --s3 -f ./myfile.zip -k remote/path/myfile.zip

# Upload entire directory (preserves structure)
keryx upload -f ./my-folder/ -k backup/my-folder/

Upload Options:

• -f, --file <FILE> - Local file or directory path (required)
• -k, --key <KEY> - S3 destination path (required)
• --s3 - Use S3 transfer (default, flag is optional)

Download Files

# Download a single file
keryx download -k remote/path/myfile.zip -f ./downloaded.zip

# Download directory/prefix
keryx download -k backup/my-folder/ -f ./restored/

Download Options:

• -k, --key <KEY> - S3 object key or prefix (required)
• -f, --file <FILE> - Local destination path (required)
• --s3 - Use S3 transfer (default, flag is optional)

List Objects

# List all objects in bucket
keryx list

Delete Objects

# Delete single file
keryx delete -k path/to/file.zip

# Delete directory (recursive, prompts for confirmation)
keryx delete -k remote/prefix/

Copy Objects

Available in version 1.0.3+

Copy objects within the same S3 bucket:

# Copy single file
keryx copy -s path/to/file.zip -d backup/file.zip

# Copy directory recursively
keryx copy -s folder/ -d backup/folder/ -r

# Preview without executing (dry-run)
keryx copy -s folder/ -d backup/ -r --dry-run

# Force overwrite existing files
keryx copy -s file.zip -d existing.zip --force

Copy Options:

• -s, --source <SOURCE> - Source S3 key or prefix (required)
• -d, --dest <DEST> - Destination S3 key or prefix (required)
• -r, --recursive - Copy recursively for directories
• --force - Overwrite without confirmation
• --dry-run - Preview operations only

Move/Rename Objects

Available in version 1.0.3+

Move or rename objects within the same S3 bucket:

# Rename single file
keryx move -s old-name.txt -d new-name.txt

# Move directory recursively
keryx move -s old-folder/ -d new-folder/ -r

# Preview without executing
keryx move -s folder/ -d archive/ -r --dry-run

# Force overwrite existing files
keryx move -s file.zip -d existing.zip --force

Move Options:

• -s, --source <SOURCE> - Source S3 key or prefix (required)
• -d, --dest <DEST> - Destination S3 key or prefix (required)
• -r, --recursive - Move recursively for directories
• --force - Overwrite without confirmation
• --dry-run - Preview operations only

Global Options

These options can be used with any command to override the active S3 profile:

keryx [OPTIONS] <COMMAND>

• -b, --bucket <BUCKET> - Override S3 bucket
• -e, --endpoint <ENDPOINT> - Override S3 endpoint URL
• --region <REGION> - Override AWS region
• --access-key <ACCESS_KEY> - Override access key
• --secret-key <SECRET_KEY> - Override secret key
• -h, --help - Print help
• -V, --version - Print version

P2P Transfers

Direct encrypted peer-to-peer file transfers. No files pass through servers.

Send a File (Sender)

# Create room and wait for receiver
keryx upload --p2p -f ./myfile.zip
# Output: Room code: abc123def456...
# Share this code with the receiver

Receive a File (Receiver)

# Join room using the code
keryx download --p2p -k <ROOM_CODE> -f ./output/

Output path behavior:

• -f ./output → saves as ./output/myfile.zip (directory)
• -f ./renamed.zip → saves as ./renamed.zip (file rename)

Directory Transfer

# SENDER
keryx upload --p2p -f ./my-project/

# RECEIVER
keryx download --p2p -k <ROOM_CODE> -f ./received/

Relay Mode

For symmetric NAT or strict firewalls where direct P2P fails. Requires paid license (Solo tier or higher).

# SENDER
keryx upload --p2p --relay -f ./myfile.zip

# RECEIVER
keryx download --p2p --relay -k <ROOM_CODE> -f ./output/

Relay mode routes through servers but maintains end-to-end encryption. The relay server only sees encrypted bytes and cannot read your files.

Auto Route Selection

Let the ML system choose between direct and relay. Requires paid license (Solo tier or higher).

keryx upload --p2p --route-auto -f ./myfile.zip

LAN Transfer Mode

For maximum speed on local networks (no signal server needed):

# RECEIVER: Start listening
keryx download --lan 0.0.0.0:9000 -f ./output/

# SENDER: Connect to receiver
keryx upload --lan 192.168.1.100:9000 -f ./myfile.zip

P2P Upload Options

• -f, --file <FILE> - Local file or directory (required)
• -k, --key <KEY> - Ignored in P2P mode
• --p2p - Use P2P transfer
• --relay - Force relay mode (paid tier)
• --route-auto - ML-based route selection
• --lan <ADDR> - Direct LAN transfer (IP:port)

P2P Download Options

• -k, --key <KEY> - Room code (required for P2P)
• -f, --file <FILE> - Local destination (required)
• --p2p - Use P2P transfer
• --relay - Force relay mode (paid tier)
• --route-auto - ML-based route selection
• --lan <ADDR> - Direct LAN listen address

License Management

Relay features require a valid license. Direct P2P is always free.

# Activate a license
keryx license activate --key KERYX-XXXX-XXXX-XXXX-XXXX

# Activate with device name
keryx license activate --key KERYX-XXXX-XXXX-XXXX-XXXX --name "Work Laptop"

# Check license status
keryx license status

# Validate license with server
keryx license validate

# Deactivate (release for use elsewhere)
keryx license deactivate

Subcommands:

• activate - Activate a license key
• deactivate - Release license from device
• status - Show current license status
• validate - Refresh license state from server

Trusted Devices

Manage SSH-style trusted P2P devices:

# List all trusted devices
keryx trust list

# Remove trust by name or peer_id
keryx trust remove "Work PC"
keryx trust remove abc123...

# Rename a trusted device
keryx trust rename "Old Name" "New Name"

# Clear all trusted devices
keryx trust clear

Subcommands:

• list - List all trusted devices
• remove <IDENTIFIER> - Remove trust by name or peer_id
• rename <IDENTIFIER> <NEW_NAME> - Rename a device
• clear - Remove all trusted devices

Watch Daemon (File Sync)

Automated file synchronization between local directories and S3. Requires paid license (Solo tier or higher).

Add a Watch Rule

# Basic local-to-S3 sync
keryx watch add \
  --name "Photos Backup" \
  --source-type local \
  --source /path/to/photos \
  --dest-type s3 \
  --dest "MyProfile:backups/photos"

# Recursive with filters
keryx watch add \
  --name "Code Sync" \
  --source-type local \
  --source /projects/myapp \
  --dest-type s3 \
  --dest "MyProfile:code/myapp" \
  --recursive \
  --include "*.rs,*.toml" \
  --exclude "target/*,*.tmp"

# Enable deletion sync (use with caution)
keryx watch add \
  --name "Mirror" \
  --source-type local \
  --source /data \
  --dest-type s3 \
  --dest "MyProfile:mirror" \
  --sync-deletes

Add Options:

• -n, --name <NAME> - Rule name (required)
• --source-type <TYPE> - "local" or "s3" (required)
• --source <PATH> - Source path or S3 location (required)
• --dest-type <TYPE> - "local" or "s3" (required)
• --dest <PATH> - Destination path or S3 location (required)
• -r, --recursive - Watch subdirectories
• --include <PATTERNS> - Include globs (comma-separated)
• --exclude <PATTERNS> - Exclude globs (comma-separated)
• --sync-deletes - Delete at destination when source deleted
• --mass-change-threshold <0-100> - Abort if too many changes (default: 90)

Manage Watch Rules

# List all rules
keryx watch list

# Show rule details
keryx watch show "Photos Backup"

# Enable/disable rules
keryx watch enable "Photos Backup"
keryx watch disable "Photos Backup"

# Remove a rule
keryx watch remove "Photos Backup"

Daemon Control

# Start the watch daemon
keryx watch start

# Stop the daemon
keryx watch stop

# Check daemon status
keryx watch status

# Manually trigger sync for a rule
keryx watch sync "Photos Backup"

# List pending conflicts
keryx watch conflicts

Subcommands:

• add - Add a new watch rule
• list - List all rules
• show <NAME> - Show rule details
• enable <NAME> - Enable a rule
• disable <NAME> - Disable a rule
• remove <NAME> - Remove a rule
• start - Start watch daemon
• stop - Stop watch daemon
• status - Show daemon status
• sync <NAME> - Manually trigger sync
• conflicts - List pending conflicts

Updates

# Check for updates
keryx update check

# Install latest update
keryx update install

# Show current version and status
keryx update status

Subcommands:

• check - Check if updates available
• install - Download and install update
• status - Show version and update status

Quick Reference

S3 Workflow

# 1. Configure credentials
keryx config --bucket mybucket --endpoint https://s3.region.wasabisys.com \
  --region us-east-1 --access-key KEY --secret-key SECRET

# 2. Upload
keryx upload -f ./file.zip -k remote/file.zip

# 3. List
keryx list

# 4. Download
keryx download -k remote/file.zip -f ./downloaded.zip

# 5. Delete
keryx delete -k remote/file.zip

P2P Workflow

# SENDER
keryx upload --p2p -f ./file.zip
# Share the room code

# RECEIVER
keryx download --p2p -k <ROOM_CODE> -f ./output/

Resume Interrupted Transfers

Simply re-run the same command - transfers resume automatically from the last chunk.

# Original (interrupted)
keryx upload -f ./large-file.zip -k backup/large-file.zip
# ^C or network drops

# Resume (within 23 hours)
keryx upload -f ./large-file.zip -k backup/large-file.zip

Troubleshooting

P2P Connection Timeout

• Check internet connectivity on both ends
• Check for firewall/VPN blocking UDP
• Try relay mode: keryx upload --p2p --relay -f ./file.zip

S3 Authentication Errors

• Verify credentials: keryx config
• Check endpoint URL format
• Ensure bucket name is correct

Transfer Stalls

• The watchdog auto-recovers from stalls
• If persistent, check network stability
• For P2P, try relay mode

For more help, contact support@netviper.gr

Disclaimer