Data Sync¶

StackOps currently splits data movement into two layers:

• devops data for repeatable, named backup entries stored in the backup config
• cloud for direct source/target copy, sync, mount, and SSH file transfer

Repeatable backups with devops data¶

Start with the current backup workflow entrypoint:

devops data --help

Current subcommands:

• sync
• register
• edit

Register a backup item¶

Add one file or directory to the user backup config:

devops data register ~/.config/wezterm --group dotfiles --encryption asymmetric
devops data register ~/.config/wezterm --group dotfiles --encryption symmetric --password "$STACKOPS_BACKUP_PASSWORD"
devops data register ~/Documents/work --group documents --path-cloud backups/work --os linux,darwin

register records fields such as:

• path_local
• path_cloud
• share_url
• encryption
• zip
• rel2home
• os

Representative entry:

dotfiles:
  wezterm:
    path_local: "~/.config/wezterm"
    path_cloud: "^"
    share_url: null
    encryption: asymmetric
    zip: true
    rel2home: true
    os:
      - linux
      - darwin

^ means "derive the remote path from path_local". path_cloud can include a cloud prefix such as od:/something. share_url is null until a share link exists. Every persisted entry requires encryption: symmetric, encryption: asymmetric, or encryption: null. null means plaintext. The short values s and a are CLI aliases only; YAML stores the full mode names. --encryption, -e is the sole encryption switch for registration. Omit it to record encryption: null. A password supplies credentials but does not select a mode, so --password requires explicit --encryption symmetric and is never stored in mapper/data.yaml.

Generate backup or restore commands¶

devops data sync is direction-based:

• up backs up to the cloud
• down restores from the cloud

Examples:

# Generate commands for every registered item
devops data sync up --which all

# Restore one group from the user backup config
devops data sync down -s user --which dotfiles

# Replace an existing restore target
devops data sync down -s user --which dotfiles --on-conflict overwrite-target

# Restrict the generated commands to one item and one cloud profile
devops data sync up --cloud myremote --which dotfiles.wezterm

# Use one password for entries that explicitly store encryption: symmetric
devops data sync up --which dotfiles.wezterm --password "$STACKOPS_BACKUP_PASSWORD"

# Restore one item from its recorded share_url instead of rclone
devops data sync down --use-link --which dotfiles.wezterm

--use-link is only valid for down. Every selected entry must have a non-null share_url; otherwise StackOps exits with the affected entry names and tells you to either remove --use-link or add valid links.

--on-conflict controls what happens when the direction's target already exists. The target is the cloud destination for up and the local destination for down. Accepted policies are:

• throw-error: stop instead of changing an existing target; this is the default
• overwrite-target: replace the existing target
• merge-target: merge the source into the existing target

Choose the policy explicitly when an existing target is expected. For example, use --on-conflict merge-target when restoring into a local directory whose target-only contents must remain.

Inspect or edit the backup config¶

devops data edit -s user
devops data edit -s library

Use --source, -s on data sync and edit commands to choose library, user, or all where supported.

Direct transfers with cloud¶

Use cloud when you want explicit source/target operations instead of registered backup items:

cloud --help

Current top-level commands:

• sync
• copy
• mount
• ftpx

Copy¶

One-off upload or download:

cloud copy ./report.pdf remote:reports/report.pdf
cloud copy remote:reports/report.pdf ./report.pdf
cloud copy ./report.pdf remote:reports/report.pdf --record-name report --record-group shared
cloud copy ./report.pdf remote:reports/report.pdf --share-type v --record-name report --record-group shared

--record-name writes the upload into the user mapper/data.yaml entry. Add --share-scope or --share-type when you also want the generated URL saved there instead of writing a .share_url_* sidecar file.

Sync¶

Ad hoc directory synchronization:

cloud sync ~/documents remote:documents
cloud sync ~/documents remote:documents --bisync

Mount¶

Mount a configured remote locally:

cloud mount --interactive

FTP-over-SSH¶

Transfer files between machine:path endpoints:

cloud ftpx localmachine:/tmp/archive remotehost:/tmp/archive --recursive

Config sources¶

The cloud commands rely on explicit CLI flags for transfer behavior. The live help shows the current flags for ad hoc operations such as:

• --root
• --encryption
• --zip
• --relative2home

If a remote path starts with :, StackOps fills in the cloud name from the configured default cloud.

Both cloud copy and cloud sync use --encryption, -e as the sole encryption switch. Accepted CLI values are symmetric/s and asymmetric/a; omitting the option keeps the transfer plaintext. Password options require an explicit symmetric mode.

Use devops data when you want durable named backup sets. Use cloud copy or cloud sync when you already know the exact source and destination you want to move.