Backup Tools

Overview

Complete backup system with risk assessment and recovery capabilities, unified into 1 tool.

Tools

`backup`

Manage all backup operations. Auto-deduces action from the parameters you provide.

Actions:

List backups (no params)

backup()
// Returns: all recent backups

Optional filters:

limit (number): Max backups to return (default: 20)
filter_operation (string): Filter by type: edit, delete, batch, all
filter_path (string): Filter by file path (substring match)
newer_than_hours (number): Only recent backups

Get backup details (action: “info”)

backup({ action: "info", backup_id: "20260301-abc123" })
// Returns: full backup metadata, files, timestamps

Compare with current file (action: “compare”)

backup({ action: "compare", backup_id: "20260301-abc123", file_path: "main.go" })
// Returns: diff showing changes since backup

Clean up old backups (action: “cleanup”)

backup({ action: "cleanup", older_than_days: 7, dry_run: true })
// Returns: preview of backups to be removed

Parameters:

action (required): "cleanup"
older_than_days (number): Delete older than N days (default: 7)
dry_run (boolean): Preview without deleting (default: true)

Restore from backup (action: “restore”)

Restore file(s) from a backup. Creates a safety backup before restoring.

// Preview what will be restored
backup({ action: "restore", backup_id: "20260301-abc123", preview: true })

// Restore all files from backup
backup({ action: "restore", backup_id: "20260301-abc123" })

// Restore specific file
backup({ action: "restore", backup_id: "20260301-abc123", file_path: "main.go" })

Restore parameters:

action (required): "restore"
backup_id (required): Backup ID from backup()
file_path (optional): Specific file to restore (default: all files in backup)
preview (optional): Show diff without restoring (default: false)
dry_run (optional): Preview without executing (alias for preview here)

Step-through undo (action: “undo_last”) — v4.3.8+

Walk the undo chain backward one step. Without file_path, undoes the most recent backup. With file_path, walks the chain for that specific file. Pass preview:true to peek without restoring.

// Most recent: undo the last change
backup({ action: "undo_last", preview: true })

// Walk the chain for a single file
backup({ action: "undo_last", file_path: "main.go", preview: true })
backup({ action: "undo_last", file_path: "main.go" })

Show undo chain (action: “undo_chain”) — v4.3.8+

backup({ action: "undo_chain", file_path: "main.go" })
// Returns: ordered list of backups for the file, oldest first

Trash workflows (v4.5.11+) — soft-delete integration

When --backup-dir is configured, delete_file (soft-delete mode) stores files at <backup-dir>/filesdelete/<sd-id>/<basename> with a metadata.json sidecar. The trash actions read and manage that area.

// List soft-deleted entries
backup({ action: "list_trash" })
backup({ action: "list_trash", filter_path: "main.go" })
backup({ action: "list_trash", older_than_days: 30 })

// Restore a single soft-deleted file
backup({ action: "restore_trash", sd_id: "sd-..." })
// → moves the file back to its original path

// Purge trash entries (dry-run first)
backup({ action: "purge_trash", older_than_days: 30, dry_run: true })
backup({ action: "purge_trash", older_than_days: 30 })
backup({ action: "purge_trash", sd_id: "sd-..." })

The Dashboard Trash tab (v4.5.12+) exposes the same entries through a web UI.

Workflow Example

1. backup()                                                        → List recent backups
2. backup({ action: "info", backup_id: "..." })                    → Backup details
3. backup({ action: "compare", backup_id: "...", file_path: "main.go" })  → Compare changes
4. backup({ action: "restore", backup_id: "...", preview: true })  → Preview restore
5. backup({ action: "restore", backup_id: "..." })                 → Execute restore

Migration from v3

v3 Tool	v4 Equivalent
`list_backups`	`backup()` (no params)
`get_backup_info`	`backup({ action: "info", backup_id: "..." })`
`compare_with_backup`	`backup({ action: "compare", backup_id: "...", file_path: "..." })`
`cleanup_backups`	`backup({ action: "cleanup", older_than_days: 7, dry_run: true })`
`restore_backup`	`backup({ action: "restore", backup_id: "..." })`

See Backups & Recovery Guide for detailed usage.