fnb — Fetch'n'Backup

fnb is a simple backup tool, powered by rsync. It gives you three handy commands: fetch (to pull from remote), backup (to save to somewhere safe), and upload (to push to remote).

Under the hood? Just good old rsync — no magic, just sharp automation.

• Simple config. Sharp execution. Safe data.
• Run fetch, backup, or upload on their own, or sync fetch + backup in one go.

🚀 Features

1. Fetch — Retrieve data from a remote server to your local machine
2. Backup — Save local data to external storage
3. Upload — Push local data to a remote server
4. Sync — Run Fetch and Backup together in one go
5. Init — Generate an initial config file (fnb.toml)
6. Structured Logging — Built-in logging with configurable verbosity levels and file output

⚙️ Installation

From PyPI (Recommended)

pip install fnb
# または
uv pip install fnb

From Source

git clone https://gitlab.com/qumasan/fnb.git
cd fnb
uv sync --all-groups
uv run fnb --help

Requirements: Python 3.12 or higher is required.

See the full Installation Guide for more options, including running from source without installing.

🧰 Quick Start

# Initialize configuration files (fnb.toml and .env files)
fnb init

# Check the current config
fnb status

# Fetch: remote -> local
fnb fetch TARGET_LABEL

# Backup: local -> external
fnb backup TARGET_LABEL

# Upload: local -> remote
fnb upload TARGET_LABEL

# Run Fetch → Backup in one go
fnb sync TARGET_LABEL

# Check version
fnb version

🔧 Configuration

fnb uses TOML configuration files with sections for fetch, backup, and upload operations:

[fetch.SECTION_NAME]
label = "TARGET_LABEL"
summary = "Fetch data from remote server"
host = "user@remote-host"
source = "~/path/to/source/"
target = "./local/backup/path/"
options = ["-auvz", "--delete", '--rsync-path="~/.local/bin/rsync"']
enabled = true

[backup.SECTION_NAME]
label = "TARGET_LABEL"
summary = "Backup data to cloud storage"
host = "none"          # Local operation
source = "./local/backup/path/"  # Output from fetch
target = "./cloud/backup/path/"
options = ["-auvz", "--delete"]
enabled = true

[upload.SECTION_NAME]
label = "TARGET_LABEL"
summary = "Upload data to remote server"
host = "user@remote-host"          # host describes the target here, not the source
source = "./local/backup/path/"
target = "~/path/to/destination/"
options = ["-auvz", "--delete"]
enabled = true

Configuration File Priority (highest to lowest)

1. ./fnb.toml — Project-local configuration
2. ~/.config/fnb/config.toml — Global user configuration (XDG standard)
3. C:\Users\username\AppData\Local\fnb\config.toml — Windows global configuration

📊 Logging

fnb includes built-in structured logging powered by loguru. All CLI commands support --log-level, --verbose (same as --log-level DEBUG), and --quiet (same as --log-level WARNING).

fnb fetch TARGET_LABEL --verbose
fnb backup TARGET_LABEL --quiet
fnb upload TARGET_LABEL --quiet
fnb sync TARGET_LABEL --log-level DEBUG

User-facing messages go to stdout; debug/technical logs go to stderr and are also saved to a rotating log file:

• macOS: ~/Library/Logs/fnb/fnb.log
• Linux: ~/.local/share/fnb/fnb.log
• Windows: %APPDATA%\qumasan\fnb\Logs\fnb.log

Set FNB_DISABLE_FILE_LOGGING=1 to disable file logging.

🔐 Authentication

SSH password input can be automated using pexpect. You can also define connection settings (e.g. FNB_PASSWORD_*, FNB_TIMEOUT) in a .env file if needed. Run fnb init env to create the initial .env file.

For a one-off connection, use --ask-password on fetch/upload/sync to type the password interactively (input hidden) instead of --ssh-password VALUE, which the shell records to history the moment you type it:

fnb fetch TARGET_LABEL --ask-password

On macOS, fnb also checks the Keychain for a fnb-{host} password item before falling back to FNB_PASSWORD_DEFAULT, so you can avoid storing passwords in plain text:

security add-generic-password -s "fnb-user@remote-host" -a "user@remote-host" -w "your-password"

On any platform, fnb can also read a GPG-encrypted password file from ~/.config/fnb/passwords/{host}.gpg (or default.gpg):

mkdir -p ~/.config/fnb/passwords
echo -n "your-password" | gpg --symmetric -o ~/.config/fnb/passwords/user_remote_host.gpg

See the Security Guide for details and other authentication options (SSH keys, dotenvx encryption).

🪪 License

MIT

🔗 Links

• 🛠️ Development, Issues, Merge Requests: GitLab — please use GitLab for development contributions, bug reports, and feature requests
• 🌏 Public Mirror and Discussions: GitHub
• 📦 PyPI Package: fnb
• 📖 Documentation: ReadTheDocs — installation, configuration, Contributor Guide, and Maintainer Guide
• 📝 Release Notes: docs/releases/

See CLAUDE.md for detailed development guidelines (testing, linting, release workflow).