Metadata-Version: 2.4
Name: fnb
Version: 0.18.0
Summary: Fetch'n'Backup - Simple two-step backup tool with rsync
Project-URL: Repository, https://gitlab.com/qumasan/fnb
Project-URL: Documentation, https://fnb.readthedocs.io/
Project-URL: Issues, https://gitlab.com/qumasan/fnb/-/issues
Author-email: "Shota Takahashi (KMI)" <shotakaha@kmi.nagoya-u.ac.jp>
License: MIT
License-File: LICENSE
Keywords: backup,cli,fetch,rsync,sync
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: loguru>=0.7.0
Requires-Dist: pexpect>=4.9.0
Requires-Dist: platformdirs>=4.3.8
Requires-Dist: pydantic>=2.11.7
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: rich>=14.3.3
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

# fnb — Fetch'n'Backup

[![PyPI version](https://badge.fury.io/py/fnb.svg)](https://pypi.org/project/fnb/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/qumasan/fnb/-/blob/main/LICENSE)

**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)

```bash
pip install fnb
# または
uv pip install fnb
```

### From Source

```bash
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](https://fnb.readthedocs.io/en/latest/installation/) for more options, including running from source without installing.

---

## 🧰 Quick Start

```bash
# 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:

```toml
[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](https://loguru.readthedocs.io/). All CLI commands support `--log-level`, `--verbose` (same as `--log-level DEBUG`), and `--quiet` (same as `--log-level WARNING`).

```bash
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.

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:

```bash
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`):

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

See the [Security Guide](https://fnb.readthedocs.io/en/latest/usage/security/) for details and other authentication options (SSH keys, dotenvx encryption).

---

## 🪪 License

MIT

---

## 🔗 Links

- 🛠️ Development, Issues, Merge Requests: [GitLab](https://gitlab.com/qumasan/fnb) — please use GitLab for development contributions, bug reports, and feature requests
- 🌏 Public Mirror and Discussions: GitHub
- 📦 PyPI Package: [fnb](https://pypi.org/project/fnb/)
- 📖 Documentation: [ReadTheDocs](https://fnb.readthedocs.io/) — installation, configuration, [Contributor Guide](https://fnb.readthedocs.io/en/latest/contributor-guide/), and [Maintainer Guide](https://fnb.readthedocs.io/en/latest/maintainer-guide/)
- 📝 Release Notes: [docs/releases/](https://fnb.readthedocs.io/en/latest/releases/)

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