Work Assets Backup (macOS)

Work Assets are used to scan the development environment configuration files (Shell, Git, SSH, Docker, Editor, etc.) in the macOS user home directory, generate a reviewable TOML plan, and then back up to the local directory as scheduled, and support verification, recovery preview, formal recovery, and cleanup.

This article describes the use of the ppk work-assets subcommand on macOS. It is recommended to do dry-run without --apply at each step, and add --apply after confirming the output.

Use Cases

• Backup “working assets” such as.zshrc,.ssh/config, VS Code configuration before switching or reinstalling the system
• Periodic snapshot development environment for easy comparison or rollback
• Disaster Preparedness Walkthrough: restore preview, then restore run to temporary directory validation

Difference from regular app backups

Complete process overview

scan（扫描生成计划）
  → apply（执行备份）
    → verify（校验备份集）
      → restore preview（恢复预演）
        → restore run（正式恢复到指定目录）
          → cleanup（清理备份集元数据）
            → 手动删除目标目录中的备份文件（可选）

Scan and generate plan

Command Example

ppk work-assets scan \
  --home ~ \
  --asset-set-key test-$(date +%Y%m%d) \
  --apply \
  --plan-file ~/.peppykeep/work-assets/plans/test.toml

General

dry-run sample output

=== Dry Run ===
Action         : work-assets scan
AssetSetKey    : test-YYYYMMDD
PlanFile       : ~/.peppykeep/work-assets/plans/test.toml
Found          : 12
Included       : 12
ReviewRequired : 0
Skipped        : 0
Warnings       : 0
Next           : Re-run with --apply to write the TOML plan.

Formal Execution Example Output

=== Completed ===
Action         : work-assets scan
Status         : TOML plan generated.

Plan file (TOML) description

Upon completion of the scan, a schedule file similar to the following will be generated (path is--plan-file):

# Plan file schema version
schema_version = "1"
# Unique id for this backup set
asset_set_key = "test-YYYYMMDD"
# Host that ran the scan
device_id = "your-host.local"
# Source home directory to scan
source_home = "/path/to/yourname"
# Backup destination (local default ref)
destination_ref = "local:default"
warnings = []

[[assets]]
# Asset id (template:path)
asset_id = "shell:.bash_profile"
# Path relative to source_home (.bash_profile → ~/.bash_profile)
path = ".bash_profile"
# Kind: file or directory
kind = "file"
# Sensitivity: low / medium / high
sensitivity = "low"
# Size in bytes
size_bytes = 515
# Action: include, exclude, review
action = "include"
# Reason: matched_template = built-in template match
reason = "matched_template"
# Matched template id
template_id = "shell"

Field Quick Lookup

Schedule can be manually edited before apply, changing the uncertainty to action = "review" or exclude.

Perform backup (apply)

Command Example

ppk work-assets apply \
  --plan-file ~/.peppykeep/work-assets/plans/test.toml \
  --apply

output example

=== Completed ===
Action               : work-assets apply
PlanFile             : ~/.peppykeep/work-assets/plans/test.toml
SourceHome           : /path/to/yourname
DestinationRef       : ~/ppk-backups
DestinationOutput    : ~/ppk-backups
DestinationPreflight : Warning
BackupSetId          : test-YYYYMMDD-<timestamp>
BackupSetDir         : ~/.peppykeep/work-assets/backup-sets/test-YYYYMMDD/...
Manifest             : .../manifest.json
CoverageReport       : .../coverage.json
AuditLog             : .../events.jsonl
Applied              : 12
Skipped              : 0
ReviewRequired       : 0
Blocked              : 0
PreflightIssues      : 1
Status               : Work asset plan applied.

Target Catalog Preflight

On the first backup, if the destination directory does not already exist, Warning (not Error) may appear:

Destination Preflight
Status : Warning
Writable : true  Listable : false  Deletable : false  FinalCommit : true
- warning  destination_directory_missing
  Destination directory does not exist yet.
  The directory can be created before the first backup.

Description: The destination directory can be automatically created before the first backup; Writable istrueto continue.

Common Configurations Included in Backups

The backup file is written to DestinationOutput and the metadata is saved under BackupSetDir.

manifest.json description

Each apply will generate manifest.json in BackupSetDir to record the metadata of this backup set. Examples of core fields:

{
  "backup_set_id": "test-YYYYMMDD-<timestamp>",
  "asset_set_key": "test-YYYYMMDD",
  "device_id": "your-host.local",
  "source_home": "/path/to/yourname",
  "destination_ref": "local:~/ppk-backups",
  "destination_output": "~/ppk-backups",
  "plan_file": "~/.peppykeep/work-assets/plans/test.toml",
  "created_at": "<unix-timestamp>",
  "destination_preflight_status": "Warning",
  "destination_preflight_issues": [
    {
      "code": "destination_directory_missing",
      "severity": "Warning",
      "message": "Destination directory does not exist yet.",
      "suggested_action": "The directory can be created before the first backup."
    }
  ],
  "plan_assets": [
    {
      "asset_id": "shell:.bash_profile",
      "path": ".bash_profile",
      "kind": "file",
      "sensitivity": "low",
      "size_bytes": 515,
      "action": "include",
      "reason": "matched_template",
      "template_id": "shell"
    }
  ]
}

There are also in the same directory:

Verify

Command Example

ppk work-assets verify \
  --asset-set-key test-YYYYMMDD \
  --apply

Output example (scenario where verify may fail)

=== Completed ===
Action         : work-assets verify
AssetSetKey    : test-YYYYMMDD
BackupSetId    : test-YYYYMMDD-<timestamp>
Report         : ~/.ppk/work-assets/reports/<backup-set-id>-verify.json
Status         : Failed
Issues         : 1

Verify Issues
- included asset missing from backup source: .nvm/alias

Reason Description

In the plan, .nvm/alias is marked as a single path asset, but apply actually backs up multiple alias files * * (such asdefault ',' lts/argon, etc.) in the .nvm/alias/* * directory. verify When checking by the path in the plan, the source side .nvm/alias is considered `missing’ and an error is reported.

Troubleshooting suggestions

• If you are just doing a recovery drill, you can use restore preview to confirm that the files in the backup directory are complete
• Before production use, pay attention to the verify report; if necessary, adjust the ’kind of '.nvm/alias in the plan or exclude this item
• Verification report path: ~/.ppk/work-assets/reports/<backup-set-id>-verify.json

restore preview

The restore preview will not be written to the source home directory, only the backup content will be mapped to the specified output directory for the walkthrough.

Command Example

ppk work-assets restore preview \
  --asset-set-key test-YYYYMMDD \
  --output-dir /tmp/wabs-restore-preview \
  --apply

output example

=== Completed ===
Action       : work-assets restore preview
OutputDir    : /tmp/wabs-restore-preview
SourceRoot   : ~/ppk-backups
Strategy     : Skip
Status       : Warning
New          : 25
Skip         : 0
Overwrite    : 0

Description: The number of preview items may be greater than the number of Applied in the plan, because catalog assets such as .nvm/alias/expand into multiple files.

Report path: ~/.ppk/work-assets/reports/<backup-set-id>-restore-preview.json

Formal restore (restore run)

After confirming that the preview is correct, you can write the backup back to the specified directory (It is still recommended to use a separate directory for the drill, do not directly overwrite the production main directory).

Command Example

ppk work-assets restore run \
  --asset-set-key test-YYYYMMDD \
  --output-dir /tmp/wabs-restore-preview \
  --apply

output example

=== Completed ===
Action      : work-assets restore run
OutputDir   : /tmp/wabs-restore-preview
Strategy    : Skip
Status      : Warning
Status      : Restore completed.

Once the restore is complete, you can check that the files under `/tmp/wabs-restore-preview’ are consistent with the backup.

Clean up the test product (cleanup)

Command Example

ppk work-assets cleanup \
  --asset-set-key test-YYYYMMDD \
  --apply

output example

=== Completed ===
Action                     : work-assets cleanup
RemovedBackupSetDir        : true
RemovedDestinationArtifact : false
Status                     : Cleanup completed.

Note: Default cleanup only deletes backup set metadata under ~/.peppykeep/work-assets/backup-sets/', **does not** delete copied files in the DestinationOutput’ directory (RemovedDestinationArtifact: false).

To also delete backup files in the destination directory, you need to:

# Option 1: Add parameters when cleanup (if CLI supports)
ppk work-assets cleanup \
  --asset-set-key test-YYYYMMDD \
  --remove-destination-artifact \
  --apply

# 方式二：手动删除目标目录中的备份文件
rm -rf ~/ppk-backups/

FAQ

Q1: What doesNext: Re-run with --applymean?

All ppk work-assets subcommands default to dry-run. --apply must be added to actually write a plan, backup, restore, or cleanup.

Q2: Where is the plan file and status directory?

Q3: Does the verification failure mean the backup is not available?

Not necessarily. For example, .nvm/alias is marked as a single file in the plan, but apply may back up multiple alias files in its directory, and verify reports that the paths are inconsistent; restore preview may still list recoverable items. We recommend previewing restore and spot-checking key files.

Q4: Will the SSH private key be backed up?

Yes. .ssh/id_rsa, id_ed25519, etc. are highly sensitive assets. Ensure that the backup destination directory permissions are secure and do not upload to untrusted storage.

Related Documents

• macOS function block index
• Disaster Preparedness Drill