wbck 2.2.0

a command line utility to perform workspace backup

Workspace Backup and Restoration Tool (wbck)

Introduction

Workspace Backup and Restoration Tool (wbck) is a utility designed to ease machine migrations and workspace setup without the fear of data loss. It backs up and restores your code folders, documents, and any other paths — each to the source that fits best (git remote, S3, or local disk).

Whether you're transitioning to a new machine or setting up a development environment elsewhere, wbck ensures your workspace is replicated exactly where it was, minimizing downtime and ensuring continuity in your workflow.

A workspace is all the data associated with a specific project or company context. You can define as many workspaces as you need and switch between them with a single command.

Features

• Per-path backup sources — each folder in your workspace can back up to git, S3, or local storage independently.
• Git-aware backup — pushes unpushed commits to the remote, and falls back to a zip archive for repos with no push access or untracked changes.
• Exact restoration — each folder is restored to its configured path relative to the workspace root, preserving your directory structure.
• Resume-safe restore — already-restored paths are skipped on re-runs, so a failed restore can be continued from where it left off.
• Workspace archival — disabled workspaces are compressed into a single full archive for long-term storage.
• Dry-run mode — validate all paths and surface per-file issues without performing any backup.
• Workspace contexts — switch between multiple workspace configurations without specifying a config path on every command, similar to kubectl config use-context.
• Targeted operations — back up or restore a single folder by name without touching the rest of the workspace.
• Config sync — reconcile paths_to_include with the folders actually on disk: auto-register new folders and cloned repos, detect moves and added git remotes, and prompt before dropping missing entries.

Installation

pip install wbck

wbck --help
usage: wbck [-h] [--version] {create,backup,restore,sync,cache} ...

Application to backup and restore my workspace data using config files

Commands:
  create    creates a new workspace
  backup    backup your workspace
  restore   restore your workspace
  sync      reconcile workspace configs with the folders on disk
  cache     manage workspace contexts

Configuration

Create a config file (<workspace>_config.json) in a configs directory. Here is a complete example:

{
  "name": "my",
  "enabled": 1,
  "workspace_path": "/Users/arpit",
  "default_source": "s3",
  "paths_to_include": [
    {
      "folder_name": "portfolio-website",
      "folder_path": "codes/portfolio-website",
      "backup_source": ["git"],
      "backup_location": "[e-mail]:argoyal/portfolio-website.git",
      "enabled": 1
    },
    {
      "folder_name": "documents",
      "folder_path": "documents",
      "backup_source": ["s3"],
      "enabled": 1
    },
    {
      "folder_name": "notes",
      "folder_path": "documents/notes",
      "backup_source": ["local"],
      "enabled": 1
    }
  ],
  "paths_to_exclude": [".venv", "node_modules", "build", "dist"],
  "source_credentials": {
    "s3": {
      "root_path": "my-backup-bucket",
      "aws_key": "",
      "aws_secret": "",
      "aws_profile": "myaws"
    },
    "local": {
      "root_path": "/Volumes/ExternalDrive/backups"
    },
    "git": {
      "auth_method": "ssh"
    }
  }
}

Config reference

Field	Description
name	Workspace identifier (e.g. my, work, acme)
enabled	1 = active workspace, 0 = archived (backup creates a single full-workspace zip)
workspace_path	Absolute path to the directory that contains the workspace folder
default_source	Fallback source (s3 or local) used when a git push fails or for workspace archival
paths_to_exclude	Folder/file names to skip when zipping (applied globally)

paths_to_include entries

Field	Description
folder_name	Display name and prefix used for backup file naming
folder_path	Path to the folder relative to <workspace_path>/<name>
backup_source	List of sources: "git", "s3", "local"
backup_location	Git remote URL (required when backup_source includes "git")
enabled	0 skips this path during backup and restore
pin_source	Optional. 1 stops wbck sync from ever changing this entry's backup_source (e.g. keep a third-party clone on S3 despite its git remote)

source_credentials

S3:

Field	Description
root_path	S3 bucket name
aws_profile	AWS CLI profile name (preferred over key/secret)
aws_key / aws_secret	AWS credentials (used if no profile is set)

Local:

Field	Description
root_path	Absolute path to the local backup directory

Git:

Field	Description
auth_method	"ssh" or "https"

Usage

1. Workspace Contexts

Point wbck at a folder containing all your config files once, then switch between workspaces by name — no need to pass --config-path on every command.

# Set the config folder
wbck cache set --config-folder $HOME/.configs/
# Config folder set to: /home/user/.configs/
# Available configs: my, work
# Switch with: wbck cache use <name>

# List available workspaces (* = active)
wbck cache show
# Config folder: /home/user/.configs/
#
#   * my
#     work

# Switch active workspace
wbck cache use work

# Clear the context cache
wbck cache clear

You can always override the active context for a single command:

wbck backup --config-path /path/to/specific_config.json

2. Backup

# Backup the active workspace
wbck backup

# Backup a specific workspace by name
wbck backup my

# Backup all workspaces in the config folder
wbck backup --all

# Backup a single folder only
wbck backup --folder-name documents

# Validate paths without performing the backup
wbck backup --dry-run

How git backup works: wbck pushes any unpushed commits to the configured remote. If the repo has uncommitted changes or the remote is not writable, it commits everything to a local local-dump branch and falls back to a zip upload via default_source.

Dry-run zips every file in each path to surface encoding or permission issues without uploading anything.

3. Restore

# Restore the active workspace
wbck restore

# Restore a specific workspace by name
wbck restore my

# Restore all workspaces in the config folder
wbck restore --all

# Restore a single folder only
wbck restore --folder-name documents

# Keep the backup on the remote after restoring
wbck restore --keep-remote-data

# Force restore a disabled (archived) workspace
wbck restore --force

Resume safety: if a restore run is interrupted, already-restored paths are automatically skipped on the next run, so you can re-run wbck restore to pick up from the failure point.

--force restores from the full-workspace archive created when enabled is set to 0 in the config.

4. Sync Configs with the Filesystem

wbck sync diffs each workspace's paths_to_include against the folders actually on disk and reconciles the config. A folder is considered a candidate when it is a direct child of a directory that already contains managed entries, so sync learns the depth of your layout from the config itself.

# Reconcile every workspace in the config folder (interactive)
wbck sync

# Reconcile a single workspace by name
wbck sync my

# Preview without writing anything
wbck sync --dry-run

# Apply additions/updates/moves without prompting
wbck sync --yes

# Register/refresh a single folder; the owning workspace is inferred
# from the path (intended for shell hooks after mkdir / git clone)
wbck sync --path ~/my/codes/new-repo --yes

What sync detects:

• New folder — registered with the workspace's default_source; if it is a git repo with an origin remote it is registered as git with backup_location set.
• Remote added later — a registered non-git folder that gains an origin remote can be switched to git (covers the mkdir → work → git remote add flow). In a full sync this always prompts per entry — git / both (git plus the current source) / keep once / pin — and choosing pin writes "pin_source": 1 into the entry so sync never proposes the flip again. Hook mode (--path) applies the flip automatically unless the entry is pinned.
• Move — a missing entry whose backup_location matches the remote of a new folder has its folder_path rewritten instead of being removed and re-added.
• Missing folder — always prompts per entry (remove / disable / skip), even with --yes, since a missing folder may simply not be restored yet.

Entries whose folder_path points outside the workspace tree (e.g. ../Library/...) are never touched.

5. Create a New Workspace

wbck create --name myworkspace --workspace-path $HOME/ --config-folder $HOME/.configs/

This creates the workspace directory at <workspace-path>/<name> and writes a starter config file to <config-folder>/<name>_config.json.

Contributing

Contributions are welcome! Feel free to submit bug reports, feature requests, or pull requests on GitHub.

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Disclaimer: This project is provided as-is, without warranty of any kind, express or implied. Use at your own risk.