boxyard

A CLI tool for managing and syncing folders ("boxes") across local and remote storage using rclone. Track metadata, organize boxes into groups, and keep everything in sync with conflict detection.

Install

pip install boxyard
# or
uv pip install boxyard

Requires rclone to be installed and configured.

Quick start

# Initialize boxyard (creates config and data directories)
boxyard init

# Create a new box from an existing folder
boxyard new ~/projects/my-project

# Sync a box to remote storage
boxyard sync my-project

# Check sync status
boxyard yard-status

# List all boxes
boxyard list

What it does

Boxyard manages folders (called "boxes") that you want to keep synced between your local machine and remote storage (S3, SFTP, or any rclone-supported backend).

Each box has:

• Data (data/) - the actual folder contents
• Metadata (boxmeta.toml) - name, groups, storage location, creation info
• Config (conf/) - optional per-box configuration that controls how data is synced
• Sync records - track what's been synced and when, enabling conflict detection

The conf/ folder

Each box can optionally have a conf/ folder containing rclone filter files that customize which files are included or excluded when syncing the box's data:

• .rclone_include - only sync files matching these patterns
• .rclone_exclude - skip files matching these patterns (if absent, the global default exclude list is used)
• .rclone_filters - combined include/exclude filter rules

During sync, the conf/ folder is synced before the data, ensuring filter rules are up-to-date before they're applied. This means filter rules travel with the box across remotes -- if you want a box to always exclude .venv/ or only include *.csv, put that in its conf/ folder and it will apply everywhere the box is synced.

Boxes are identified by a unique ID ({timestamp}_{subid}, e.g. 20251122_143022_a7kx9) and organized into groups via symlinks.

Commands

doctor

boxyard doctor runs a strictly read-only health check of the machine's boxyard state, so misuse and drift get caught mechanically. It never mutates or auto-fixes anything, and exits with code 0 when healthy and 1 when there is any finding — so it can run under cron/supervisors and be asserted by scripts and agents.

boxyard doctor                 # full check, including remote storage
boxyard doctor --no-remote     # offline: skip checks that access remote storage
boxyard doctor -o json         # machine-readable report

Checks:

Every finding comes with a one-line hint on how to fix it.

Configuration

Config file: ~/.config/boxyard/config.toml

default_storage_location = "my-remote"
boxyard_data_path = "~/.boxyard"
user_boxes_path = "~/boxes"
user_box_groups_path = "~/box-groups"

[storage_locations.my-remote]
storage_type = "rclone"
store_path = "boxyard"

Storage locations are defined as rclone remotes. Boxyard uses its own rclone config at ~/.config/boxyard/boxyard_rclone.conf.

Directory layout

~/.config/boxyard/
    config.toml              # Main config
    boxyard_rclone.conf      # rclone config for remotes

~/.boxyard/
    local_store/{remote}/    # Local copies of box data
    sync_records/            # Per-box sync state
    locks/                   # File locks for concurrent operations

~/boxes/                     # Symlinks to box data folders
~/box-groups/                # Group symlinks (e.g. ~/box-groups/work/my-project)

Development

Boxyard uses nblite for notebook-first development. Source files in src/boxyard/ are autogenerated -- edit the .pct.py files in pts/ instead.

uv sync                  # Install dependencies
nbl export --reverse     # Sync pts -> nbs (after editing .pct.py files)
nbl export               # Export nbs -> src/boxyard/
pytest src/tests/        # Run tests

License

MIT