sbackup-cli 2.0.0

智能文件夹备份工具，支持增量备份和自定义配置

Sbackup

A lightweight, efficient folder backup tool with CLI support for managing backup strategies.

English | Deutsch | Espanol | Francais | Portugues | Pycckuu | 日本語 | 한국어 | 中文

• Introduction
• Features
• Getting Started
  • Installation
  • Usage
• Configuration
  • Example Configuration
• SFTP Remote Backup
• WebDAV Remote Backup
• How It Works
• Development Guide
  • Running Tests
  • Code Structure
• FAQ
• Contributing
• License
• Author

---

Introduction

Sbackup is a lightweight folder backup tool that lets you add, remove, and manage backup strategies from the command line. It uses each folder's last-modified timestamp to determine whether a backup is needed, keeping your data up to date.

Features

• Incremental backup -- only folders that have changed are backed up, saving time and storage
• Multi-format support -- ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst, 7z; both global and per-entry format overrides
• SFTP remote backup -- built on paramiko with password/SSH key authentication and auto-detection of default keys
• WebDAV remote backup -- uses Python's standard library urllib with zero extra dependencies; works with Jianguoyun, NextCloud, and Synology
• S3 cloud storage -- powered by minio, supports all S3-compatible backends (AWS, MinIO, Alibaba Cloud OSS, etc.)
• Multi-destination parallel backup -- back up to local and multiple remote targets simultaneously
• Restore -- extract backups to a target directory with optional selective recovery
• Backup cleanup -- automatically delete old backups by count, age, or daily retention policy
• Encrypted backup -- 7z password encryption plus PBKDF2 encryption for all formats
• Scheduled backup -- run backups on a fixed interval or monitor the filesystem in real time with watchdog
• Backup history -- timestamps, file sizes, and SHA256 checksums recorded for every backup
• Audit log -- audit events for all backup and restore operations
• Pre/Post hooks -- run custom commands before or after backups
• Configuration profiles -- save, switch, import, and export multiple configuration profiles
• Cross-archive search -- search for matching filenames across multiple backup archives
• Data integrity -- SHA256 checksum generation and verification, Reed-Solomon error correction codes
• Config validation -- automatic validation of configuration parameters with tamper detection
• Task queue -- manage backup tasks with add, execute, and cancel operations
• Compression benchmark -- compare compression performance across formats and levels
• Disk space estimation -- estimate backup size by file type and check destination space
• Internationalization -- nine languages: Chinese, English, French, Spanish, Russian, German, Japanese, Portuguese, Korean
• Shell completion -- auto-completion for bash, zsh, fish, and PowerShell
• Lightweight and efficient -- small footprint, fast startup, low resource usage
• Cross-platform -- Windows, macOS, and Linux

Getting Started

Installation

Install with pip

pip install sbackup-cli

After installation, use the sbackup command (PyPI package name is sbackup-cli, CLI command is sbackup).

Install from source

git clone https://github.com/xiatianxuan/sbackup.git
cd sbackup
uv sync

Usage

Basic syntax

uv run python main.py <command> [options]

Available commands

Command	Description
add	Add a backup strategy
rm / remove	Remove a backup strategy
edit	Edit an existing backup strategy
all	List all backup strategies
save	Run backup
watch	Run backup on a schedule
restore	Restore from a backup file
info	View backup file details
diff	Compare source directory against backup
verify	Verify backup file integrity
search	Search for files inside a backup
xsearch	Search across multiple backup archives
versions	View backup version history
sftp	SFTP remote backup management
webdav	WebDAV remote backup management
remote	Remote file management (list/rm)
task	Backup task queue management
audit	Audit log queries
hooks	Manually run Pre/Post hooks
profile	Configuration profile management
rotate	Backup rotation cleanup
clean	Clean old backups
diskcheck	Disk space estimation
benchmark	Compression format benchmark
integrity	Backup directory integrity check
dry-run	Preview backup file selection
export / import	Export/import backup strategies
ignore	Generate .sbackupignore file
schedule	Export scheduled task configuration
webhook	Configure webhook presets
config	Configuration encryption/validation
report	Generate backup report
completion	Generate shell completion scripts
wizard	Interactive configuration wizard
status	Backup status dashboard
version	Show version information
help	Show help information

Global options

Option	Description
--lang zh_CN / en_US / fr_FR / es_ES / ru_RU / de_DE / ja_JP / pt_BR / ko_KR	Set UI language (persisted in config.json)
--format zip / tar / tar.gz / tar.bz2 / tar.xz / tar.zst / 7z	Set archive format (persisted in config.json)
--debug	Enable debug logging

Adding a backup strategy

uv run python main.py add <source> <dest> [-i ignore_patterns]

Parameters:

• source -- path to the folder to back up
• dest -- path where backup files are stored
• -i, --ignore -- comma-separated names of files or folders to skip (default: .git,__pycache__)
• --format -- per-entry archive format (overrides the global default for this strategy only): zip / tar / tar.gz / tar.bz2 / tar.xz / tar.zst / 7z

Examples:

# Add strategy using the global default format
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git

# Specify tar.gz for this strategy (every backup of this folder uses tar.gz)
uv run python main.py add F:/my_folder F:/backup --format tar.gz

# Specify 7z for this folder only
uv run python main.py add F:/my_folder F:/backup --format 7z

Removing a backup strategy

uv run python main.py rm <path>

Parameters:

• path -- source folder path of the strategy to remove

Example:

uv run python main.py rm F:/my_folder

Listing all backup strategies

uv run python main.py all

Displays all currently configured backup strategies.

Running a backup

# Use default format (ZIP)
uv run python main.py save

# Use tar.gz format
uv run python main.py --format tar.gz save

# Keep only the 5 most recent backups, auto-clean old ones
uv run python main.py save --keep 5

# Use 7z format with encryption
uv run python main.py --format 7z save --password mysecret

# English UI + tar.xz format
uv run python main.py --lang en_US --format tar.xz save

save options:

Option	Default	Description
--keep N	0	Keep the N most recent backup files; 0 means no cleanup
--password PASSWORD	""	Encryption password (7z format only)
--sftp	false	Upload to SFTP server after backup
--webdav	false	Upload to WebDAV server after backup

Backs up changed folders automatically according to the configured strategies.

Scheduled backup

# Back up every 60 minutes
uv run python main.py watch --interval 60

# Back up every 2 hours, keep the 10 most recent files
uv run python main.py watch --interval 120 --keep 10

# Scheduled backup + 7z encryption
uv run python main.py --format 7z watch --interval 60 --password mysecret

watch options:

Option	Default	Description
--interval MINUTES	60	Backup interval in minutes
--keep N	0	Keep the N most recent backup files
--password PASSWORD	""	Encryption password (7z format only)
--sftp	false	Upload to SFTP server after each backup
--webdav	false	Upload to WebDAV server after each backup

Press Ctrl+C to stop scheduled backup.

Restoring a backup

uv run python main.py restore <backup_file> <target_dir>

Parameters:

• backup_file -- path to the backup file (supports .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z)
• target_dir -- directory to restore into

Examples:

uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
uv run python main.py restore F:/backup/my_folder.7z F:/restored
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored

SFTP remote backup

# ============ Quick start (recommended) ============
# 1. Configure SFTP (auto-detects SSH private key, no manual setup needed)
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups

# 2. Test connection
sbackup sftp test

# 3. Run backup and upload
sbackup save --sftp

# ============ Authentication methods ============

# Method 1: Auto-detect private key (recommended)
# Automatically tries ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa
sbackup sftp config --host 192.168.1.100 --user admin

# Method 2: Password authentication
sbackup sftp config --host 192.168.1.100 --user admin --password secret

# Method 3: Specify private key
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa

# Method 4: Private key + passphrase (interactive input)
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa

# Method 5: Private key + passphrase (command line)
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass

# ============ Use cases ============

# One-time backup with upload
sbackup save --sftp

# Scheduled backup with auto-upload (every 60 minutes)
sbackup watch --interval 60 --sftp

# Specify format + upload
sbackup --format tar.gz save --sftp

# Encrypted backup + upload
sbackup --format 7z save --password mysecret --sftp

# Keep 5 most recent backups + upload
sbackup save --keep 5 --sftp

# ============ Advanced usage ============

# Interactive configuration (step-by-step input)
sbackup sftp config

# Non-interactive configuration (all parameters on command line)
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups

# Test connection with verbose logging
sbackup --debug sftp test

sftp subcommands:

Subcommand	Description	Example
sftp config	Configure SFTP connection (host/port/user/password/key_file/key_passphrase/remote_path)	sbackup sftp config --host 192.168.1.100 --user admin
sftp test	Test whether the SFTP connection works	sbackup sftp test

Authentication methods:

Method	Parameters	Description	Example
Auto-detect	(none)	Automatically tries ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa (recommended)	sbackup sftp config --host ... --user ...
Password	--password	Log in with a password	sbackup sftp config --host ... --user ... --password secret
Private key	--key-file	Log in with a specific SSH private key	sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa
Private key + passphrase	--key-file + --key-passphrase	When the private key requires a passphrase	sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass

Supported key formats: RSA, Ed25519, ECDSA.

Cross-platform path support:

Platform	Key path example	Description
Linux/macOS	~/.ssh/id_rsa	Expands to /home/user/.ssh/id_rsa
Windows	~/.ssh/id_rsa	Expands to C:\Users\username\.ssh\id_rsa
All platforms	Absolute path	Use the full path directly

SFTP configuration is stored in the sftp field of config.json and can be set via command line or interactive input.

Viewing version information

sbackup version

Configuration

Sbackup supports customization through a config.json file placed in the project root directory.

Configuration options

{
  "compression_format": "ZIP",
  "compression": {
    "algorithm": "ZIP_DEFLATED",
    "level": 6
  },
  "skip_patterns": [".git", "__pycache__"],
  "data_file": "sbackup.json",
  "lang": "zh_CN",
  "password": "",
  "sftp": {
    "host": "",
    "port": 22,
    "user": "",
    "password": "",
    "key_file": "",
    "key_passphrase": "",
    "remote_path": "/",
    "enabled": false
  }
}

Key	Type	Default	Description
compression_format	string	"ZIP"	Archive format: ZIP, TAR, TAR_GZ, TAR_BZ2, TAR_XZ, TAR_ZST, 7Z
compression.algorithm	string	"ZIP_DEFLATED"	ZIP compression algorithm: ZIP_DEFLATED, ZIP_STORED, ZIP_BZIP2, ZIP_LZMA
compression.level	int	6	Compression level 0-9 (0 = no compression, 9 = maximum)
skip_patterns	list	[".git", "__pycache__"]	File/folder patterns to skip (supports fnmatch wildcards and path matching)
data_file	string	Platform default	Path to the backup strategy data file
lang	string	"zh_CN"	UI language: zh_CN, en_US, fr_FR, es_ES, ru_RU, de_DE, ja_JP, pt_BR, ko_KR
password	string	""	7z encryption password
sftp.host	string	""	SFTP server address
sftp.port	int	22	SFTP port
sftp.user	string	""	SFTP username
sftp.password	string	""	SFTP password (for password authentication)
sftp.key_file	string	""	SSH private key file path (for key-based authentication)
sftp.key_passphrase	string	""	Private key passphrase (if required)
sftp.remote_path	string	"/"	Remote destination path
sftp.enabled	bool	false	Whether SFTP is enabled

Example configuration

Using tar.bz2 format for high-compression backups:

{
  "compression_format": "TAR_BZ2",
  "compression_level": 9,
  "skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
  "data_file": "backup_strategies.json",
  "lang": "en_US"
}

Archive format comparison

Format	Extension	Compression	Speed	Dependencies	Best for
ZIP	.zip	Medium	Fast	stdlib	General purpose, best Windows compatibility
tar	.tar	None	Very fast	stdlib	Archive only, pair with external compression
tar.gz	.tar.gz	Medium	Fast	stdlib	General Linux/macOS use
tar.bz2	.tar.bz2	High	Medium	stdlib	High-compression archives
tar.xz	.tar.xz	Highest	Slow	stdlib	Long-term archiving, space-sensitive
tar.zst	.tar.zst	Medium-high	Very fast	zstandard	Modern workloads, speed/size balance
7z	.7z	Very high	Slow	py7zr	Maximum compression, encryption support

WebDAV remote backup

WebDAV is an HTTP-based file protocol supported by Jianguoyun, NextCloud, Synology, and other popular cloud drives. Uses Python's standard library urllib with zero extra dependencies.

# ============ Quick start ============
# 1. Configure WebDAV
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user [e-mail] --password secret

# 2. Test connection
sbackup webdav test

# 3. Run backup and upload
sbackup save --webdav

# ============ Use cases ============

# One-time backup with upload
sbackup save --webdav

# Scheduled backup with auto-upload (every 60 minutes)
sbackup watch --interval 60 --webdav

# Specify remote subdirectory
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user [e-mail] --remote-path /backups/sbackup

# Upload to SFTP and WebDAV simultaneously
sbackup save --sftp --webdav

# ============ Common WebDAV service URLs ============
# Jianguoyun: https://dav.jianguoyun.com/dav/
# NextCloud: https://your-server/remote.php/dav/files/username/
# Synology: https://your-synology:5006/webdav/

webdav subcommands:

Subcommand	Description	Example
webdav config	Configure WebDAV connection (url/user/password/remote_path)	sbackup webdav config --url ... --user ...
webdav test	Test whether the WebDAV connection works	sbackup webdav test

Option	Default	Description
--url URL	""	WebDAV server URL (e.g. https://dav.jianguoyun.com/dav/)
--user USER	""	WebDAV username (usually an email address)
--password PASS	""	WebDAV password (Jianguoyun requires generating an app password in settings)
--remote-path PATH	/	Remote destination path

How It Works

Sbackup implements backup through the following mechanisms:

1. Strategy storage -- backup strategies are stored in a JSON file containing folder paths, last-modified timestamps, target paths, ignore patterns, and per-entry archive formats.
2. Incremental backup -- by comparing each folder's last-modified timestamp, only changed folders are backed up.
3. Multi-format compression -- uses Python's built-in zipfile and tarfile modules, plus zstandard and py7zr third-party libraries, supporting seven archive formats.
4. Per-entry format -- each strategy can specify its own archive format (add --format), which takes priority over the global --format setting; when not specified, the global default is used.
5. Backup cleanup -- after a successful backup, the target directory is scanned, sorted by modification time, and older files exceeding the retention count are deleted.
6. Encrypted backup -- the 7z format supports LZMA2 encryption via the --password parameter or the password field in config.json.
7. Scheduled backup -- the watch command runs backups in a loop at the specified interval; Ctrl+C exits safely.
8. Backup history -- each backup records a timestamp, file size, and file count, keeping the 100 most recent entries.
9. SFTP remote backup -- an SFTP client built on paramiko with connection testing, automatic remote directory creation, and progress-bar file uploads.

Data file format

{
  "/path/to/source/folder": [
    1719235200.0,
    "/path/to/target/folder",
    [".git", "__pycache__"],
    ""
  ],
  "/path/to/another/folder": [
    1719235200.0,
    "/path/to/another/target",
    [".git"],
    "TAR_GZ"
  ],
  "_history": [
    {
      "time": "2026-05-01T12:00:00",
      "source": "/path/to/source/folder",
      "size_mb": 12.5,
      "files_count": 150
    }
  ]
}

Each backup strategy entry is a 4-element list: [mtime, target, skip_patterns, compression_format]

Field	Description
mtime	Last-modified timestamp of the source folder (used for incremental backup decisions)
target	Target path where backup files are stored
skip_patterns	List of file/folder patterns to skip
compression_format	Per-entry archive format (empty string means use the global default)

Development Guide

Running tests

uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m

Code structure

sbackup/
├── main.py              # Entry point
├── sbackup/
│   ├── __init__.py      # Core function exports
│   ├── __main__.py      # python -m sbackup entry point
│   ├── cli.py           # CLI argument parsing and command dispatch (30+ commands)
│   ├── config.py        # Configuration loading, encryption, webhook/SMTP config
│   ├── auto_save.py     # BackupManager core engine
│   ├── compression.py   # 7-format compression/decompression engine
│   ├── i18n.py          # Internationalization (9 languages)
│   ├── sftp.py          # SFTP remote backup client (paramiko)
│   ├── webdav.py        # WebDAV remote backup client (zero dependencies)
│   ├── cloud_storage.py # S3 cloud storage client (minio)
│   ├── multi_dest.py    # Multi-destination parallel backup
│   ├── handlers.py      # SFTP/WebDAV/Remote/Schedule command handlers
│   ├── hooks.py         # Pre/Post hook execution
│   ├── audit.py         # Audit log system
│   ├── profile.py       # Configuration profile management
│   ├── selective.py     # Selective restore
│   ├── cross_search.py  # Cross-archive search
│   ├── integrity.py     # SHA256 checksums
│   ├── rotation.py      # Backup rotation policies
│   ├── dryrun.py        # Dry-run preview
│   ├── diskcheck.py     # Disk space estimation
│   ├── task_queue.py    # Task queue system
│   ├── schema.py        # Configuration validator
│   ├── benchmark.py     # Compression benchmarks
│   ├── chunked_backup.py# Block-level incremental backup
│   ├── dedup.py         # File-level SHA256 deduplication
│   ├── export.py        # Metadata export (CSV/JSON)
│   ├── monitor.py       # watchdog filesystem monitor
│   ├── lock.py          # Cross-platform process lock
│   ├── retry.py         # Exponential backoff retry
│   ├── ratelimiter.py   # Token bucket rate limiter
│   ├── keychain.py      # System keychain integration
│   ├── parity.py        # Reed-Solomon error correction
│   ├── completion.py    # Shell auto-completion
│   ├── wizard.py        # Interactive configuration wizard
│   └── locales/         # Translation files for 9 languages
└── tests/
    └── sbackup/
        └── test_*.py    # 30 test files covering all modules

Adding new features

1. Create a new module file under sbackup/
2. Import the new functions in sbackup/__init__.py
3. Add command-line command handling in the run() function
4. Add corresponding test files under tests/

FAQ

Q: What if the backup strategy file is accidentally deleted?

A: Backup strategies are stored in the data file. If accidentally deleted, you can re-add them by running the add command again.

Q: How do I modify an existing backup strategy?

A: Use the sbackup edit command: sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>.

Q: Is remote backup supported?

A: Yes! Three remote backup methods are available:

• SFTP: configure with sbackup sftp config, upload with sbackup save --sftp
• WebDAV: configure with sbackup webdav config, upload with sbackup save --webdav (supports Jianguoyun, NextCloud, Synology)
• S3 cloud storage: configure the cloud field in config.json, upload with sbackup save --cloud
• Multiple can be combined: sbackup save --sftp --webdav --cloud

Q: What is the difference between tar.gz and ZIP?

A: tar.gz is more common on Linux/macOS with slightly better compression; ZIP is more universal on Windows with the best compatibility. tar.bz2 and tar.xz offer higher compression but are slower. tar.zst is a modern algorithm that is extremely fast with good compression. 7z has the highest compression and supports encryption.

Q: How do I encrypt a backup?

A: Use the 7z format with a password: uv run python main.py --format 7z save --password yourpassword. The password can also be set in the password field of config.json.

Q: How do I automatically clean old backups?

A: Use the --keep parameter: uv run python main.py save --keep 5 keeps only the 5 most recent backup files. This also works with scheduled backups: uv run python main.py watch --interval 60 --keep 10.

Q: How do I set up scheduled backups?

A: Use the watch command: uv run python main.py watch --interval 60 backs up every 60 minutes. Press Ctrl+C to stop.

Q: Is password storage secure?

A: SFTP passwords and 7z encryption passwords in config.json are stored in plain text. Ensure that the config.json file is accessible only to trusted users (e.g. chmod 600 config.json). Do not commit config.json containing passwords to version control.

Contributing

Issues and Pull Requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Code style

This project follows PEP 8 and the Google Python Style Guide. Please ensure your code:

• Uses type annotations
• Follows Google-style docstrings
• Passes all unit tests

License

This project is licensed under the GNU GPL v3.0 License. See the LICENSE file for details.

Author

xiatianxuan (CodeSeed)

• Gitee
• Homepage

Special Thanks

• Xnors Studio

Contact

For questions or suggestions, please email: [e-mail]

---

Last updated: June 19, 2026