Product Overview

Create Recoverable Copies of Critical Data

PeppyKeep is a backup and recovery tool for critical data and business systems. With timeline-based versions, multiple replicas, and recovery drills, it helps organizations, teams, and individuals build backups they can actually recover—not just unverified file copies.

PeppyKeep is suitable as a standalone backup tool, or as a backup, synchronization, and recovery verification tool outside the business system, reducing the impact of accidental deletion, equipment failure, configuration damage, service abnormalities, and operational errors.

What Problems It Solves

Copying files or writing them to a backup disk does not guarantee recoverability. Common risks include:

• Incomplete backup scope, missing configuration file, business file or database;
• The backup file exists, but there is no clear point in time and version relationship;
• There is only one copy that cannot be retrieved after a device or storage failure;
• Missing encryption key, database connection or recovery dependency;
• The backup task shows success, but the real recovery process has never been verified.

PeppyKeep brings backup scope, configuration, versions, replicas, and recovery validation into one traceable workflow, so you can answer the key questions: what was backed up, when, where it is stored, and whether it can be recovered.

The Full Backup-to-Recovery Lifecycle

1. Select the critical data, application directories, configuration files, or databases you need to protect.
2. Use a configuration template to define the backup scope, exclude rules, destinations, schedule, and retention policy.
3. Run a dry run first to verify paths, permissions, connections, keys, and the planned output.
4. Create versioned backups on a timeline and save them locally or to multiple independent replicas.
5. Regularly check backup results and download or decrypt actual restore points.
6. Run recovery drills in an isolated environment to verify that files, databases, application configuration, and critical dependencies are usable.
7. Use drill results to refine the backup scope, number of retained versions, cleanup rules, and recovery runbook.

Core Capabilities

• File and directory backup: Create recoverable copies of critical data, application directories, configuration files, and business files.
• Database backup: Back up MySQL and other databases; combine with application files for a complete restore point.
• Universal application-aware backup: For business systems with well-defined data layout and recovery dependencies—for example MySQL-backed apps. Keeps databases, application files, configuration, and dependencies on one timeline.
• Dedicated application-aware backup: For app-specific data models and sync semantics—work assets, AI Agent DB/config, design files, customer data, and more—with additional app types planned.
• Timeline and versioning: Each backup keeps a clear timestamp, config revision, and restore point so you can pick the right version to restore.
• Multiple replicas and retention: Local copies, object storage, cloud drives, and multi-site replica strategies using your existing infrastructure.
• Encryption and key management: Customer-managed keys for encrypted backups; public keys encrypt backups, private keys and passphrases stay under your control.
• Large files and directories: Split archives, checksums, and task state for datasets too large for a single bundle.
• Recovery validation and drills: Verify download, decrypt, unpack, DB import, file integrity, and app dependencies—not just job success.
• Shift-left risk checks: dry-run, structural validation, coverage reports, and audit logs to surface gaps before they bite.

Use Cases

• Protection of the core business data, profiles and work results of the enterprise or team;
• File or directory backups, and restores after accidental deletion of files, directories, or historical configurations;
• The database and application files need to be backed up by the business system in the same timeline;
• Universal application-aware backup—for example MySQL-backed business systems;
• Dedicated application-aware backup—for work assets, AI Agent DB/config, design files, and customer data;
• An environment that requires multiple backup copies to be retained across devices, nodes, or locations;
• Teams that need to regularly validate real recovery links, meet internal audit or disaster preparedness requirements;
• Large files, large directories, encrypted backups and volume transfer scenarios;
• Teams who want a standalone tool to perform backup, synchronization, and recovery drills.

Capability tiers

See the PeppyKeep website for current subscription details and feature availability.

Platforms and deployment

The PeppyKeep CLI runs on Windows, macOS, and Linux. The desktop UI is in development for Windows and macOS (no Linux desktop app); Linux is CLI-only but can be managed from Windows or macOS desktop clients. See Desktop UI.

Product scope

PeppyKeep does not currently offer managed storage. Users are responsible for their own selection and management of local disks, network disks, S3-compatible object storage, or other destinations, and for their capacity, permissions, availability, retention policies, and security configurations.

PeppyKeep is responsible for the execution of backup tasks, transfer orchestration, version management, and recovery verification, and does not replace storage services, the business system’s own high-availability mechanisms, application health checks, or full disaster recovery switching processes. Encrypted private keys and passwords are kept by the user and may not be recoverable if lost.

Start with One Critical Data Set

Select a device or critical data first, use the configuration template to complete a backup, recovery, and verification, and then gradually expand to more systems and backup copies. It is recommended to perform a dry-run and recovery drill on the tester to confirm the configuration, permissions, key, and recovery path before applying it to the production environment or critical data.

Install and get started · Backup and restore scenarios · Visit PeppyKeep

Get Started

Please complete the download and installation on the official website before returning to this manual to configure the first backup plan.

Download & Install

Go to the PeppyKeep official website download page to download and install

The download page provides installation options for each platform. This manual does not repeat the maintenance installation scripts and installation steps; after installation is complete, configure and perform the first backup as per the Windows user manual or macOS and Linux command line function guide.

The desktop is in development and plans to only support Windows and macOS; Linux only supports the command line, but can be invoked or managed by the Windows or macOS desktop.

Next Steps

1. Confirm Prerequisites (including installation and default configuration)
2. Review and modify the auto-generated items in the profile
3. Create a backup plan by applicable scenario in the product description or Backup Policy and Task Management

Pre-conditions

general

1. Completed installation; default config dir contains installer-generated app.toml, bak.toml, and prj.toml, tuned for your environment
2. The user executing the backup/restore command has read/write permissions on log_dir, local_bak_home, local_tmp_home, data_dir in the configuration
3. First execution may trigger device binding login, please complete authorization before timeout

Windows

1. User has permission to write % temp %, % LOCALAPPDATA % and user level path
2. No admin permissions required
3. Default configuration directory: % USERPROFILE %\ .peppykeep\ conf (generated at installation)

macOS / Linux

1. The user has permission to write to the configuration directory and backup directory under /tmp
2. Default configuration directory: ~/.peppykeep/conf (generated during installation)
3. The mysqldump/’mysql` client can be accessed natively or within a container if MySQL backup is enabled

Optional Dependencies

User guide overview

This manual is for PeppyKeep users and is organized according to the “Prerequisite → Profile → Platform Installation → Function Block Operation”, which corresponds to the backup, recovery, cleaning, encryption, object storage and other capabilities in the product profile design.

reading order

1. Prerequisites — Installation, permissions and default configuration directory
2. Profile — Install auto-generated app.toml, bak.toml, prj.toml and bulk MySQL request files that need to be created manually
3. Choose Platform
   • Windows — Installation and function blocks
   • macOS and Linux Command Line Features Guide — Shared command line installation and function blocks

Platform Support Boundaries

The PeppyKeep command line is supported on Windows, macOS, and Linux. Desktop is in development and plans to only support Windows and macOS; Linux does not provide desktop, but can be invoked or managed by Windows or macOS desktop.

Relationship to Command Reference

The function block document focuses on the complete steps of “Configure by Scene + Preview + Execute”; for details of the parameters of each command, see Command Reference.

Reference configuration

The sample manual aligns the generated configuration directory by default after installation:

• macOS / Linux：~/.peppykeep/conf
• Windows：%USERPROFILE%\.peppykeep\conf

Wherein prj_key = test_717_file, data_dir and bak.toml in the path, encryption, object storage and other fields are consistent with the current test environment.

Configuration Files

PeppyKeep drives backups, restores, cleanups, and walkthroughs with TOML files in the configuration directory.

After installation is complete, app.toml, bak.toml, prj.toml will be automatically generated in the default configuration directory. Before performing the backup for the first time, make sure that these three files exist, and modify the connection information, backup path, object storage and other fields according to the actual environment.

Please refer to the download page of the official website of PeppyKeep for installation and updates; the retention and update rules of existing profiles are subject to the instructions on the download page.

Default configuration directory:

• macOS / Linux：~/.peppykeep/conf
• Windows：%USERPROFILE%\.peppykeep\conf

See Prerequisites for environmental requirements.

Directory Structure

conf/
├── app.toml                  # Basic PeppyKeep runtime settings (defaults usually fine)
├── bak.toml                  # Backup engine, object storage, MySQL, encryption, recovery, drills (auto-generated at install)
├── prj.toml                  # Project identity, data dirs, remote retention (auto-generated at install)
└── mysql_bak_request.toml    # Bulk MySQL backup requests (create manually as needed)

File duties

Usage

Specify the configuration directory through --config-home when executing the command (the above default directory is usually used when omitted):

peppykeep backup run --config-home /path/to/user/.peppykeep/conf

You can also set the environment variable PPK to point to the same directory, omitting --config-home.

Configuration Instructions Portal

• app.toml
• bak.toml
• prj.toml
• mysql_bak_request.toml

App profile description (app.toml)

This file is the basic configuration file required for PeppyKeep to run. It is automatically generated during installation, and it is recommended to keep the defaults, which usually do not need to be modified; only adjust the relevant fields when explicitly required by the specific feature documentation.

Field reference

[log.tracing]

[site]

Platform path differences

Configuration fields and behavior are the same on every operating system; only directory syntax differs.

macOS / Linux：

[log.tracing]
dir = "/tmp/log/peppykeep"
file_name = "app.log"
level = "info"

[site]
official_site_base_url = "https://www.peppykeep.com"

Windows：

[log.tracing]
dir = "C:\\Users\\<Username>\\AppData\\Local\\Temp\\log\\peppykeep"
file_name = "app.log"
level = "info"

[site]
official_site_base_url = "https://www.peppykeep.com"

Backup profile description (bak.toml)

This document defines the global operating parameters of the backup engine, including backup type and storage location, remote SSH, S3 compatible object storage, MySQL connection, backup encryption, recovery decryption, MySQL recovery target, and disaster recovery exercise workspace.

Configuration essentials

[public]

peppykeep backup run --no-upload temporarily saves locally only; --upload temporarily performs an upload. Command-line arguments affect only that run and do not modify the configuration file.

Remote access, object storage, and backup source

Encryption, recovery, and drills

With execution_mode = "native" in [restore.mysql], mysql_client_path points to the host’s mysql client. With container_exec, also configure the in-container mysql-client path plus container_runtime (docker or podman), container_runtime_path, and container_name. Recovery and drills must not overwrite the source database by default; change allow_restore_to_source_db and options that delete the target database only after confirmation.

Platform path and tool differences

Configuration sections and fields are identical; only local directories and executable locations differ. Use your actual installation paths rather than copying paths that do not exist.

Minimal example

The following examples show the common structure. Replace passwords, access keys, and real host addresses with secure, actual values. Commands such as peppykeep backup run and peppykeep restore mysql use the same arguments on Windows, macOS, and Linux; only the directories and tool paths in configuration need platform-specific changes.

macOS / Linux：

[public]
bak_type = "app_data"
bak_location_type = "local_and_remote"
history_bak_num = 3
log_dir = "/tmp/logs/peppykeep"
local_bak_home = "/var/lib/peppykeep/backup"
local_tmp_home = "/tmp/peppykeep"
max_bak_queue_size = 1

[object_storage]
enabled = true
provider = "s3"
bucket = "my-backup-bucket"
prefix = "peppykeep"
endpoint = "https://s3.example.com"
region = ""
path_style = false

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "backup_user"
mysql_pwd = "<provide-securely>"
mysqldump_path = "/usr/bin/mysqldump"
skip_ssl = true

[restore.mysql]
execution_mode = "native"
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "restore_user"
mysql_pwd = "<provide-securely>"
mysql_client_path = "/usr/bin/mysql"
workspace_home = "/tmp/ppk-restore-mysql"
allow_restore_to_source_db = false
drop_target_db_before_restore = false
default_check_sql_enabled = true
custom_check_sql_file = ""
keep_workspace_on_success = true
keep_workspace_on_failure = true

Windows：

[public]
bak_type = "app_data"
bak_location_type = "local_and_remote"
history_bak_num = 3
log_dir = "C:\\Users\\<Username>\\AppData\\Local\\Temp\\logs\\peppykeep"
local_bak_home = "D:\\PeppyKeep\\backup"
local_tmp_home = "C:\\Users\\<Username>\\AppData\\Local\\Temp\\peppykeep"
max_bak_queue_size = 1

[object_storage]
enabled = true
provider = "s3"
bucket = "my-backup-bucket"
prefix = "peppykeep"
endpoint = "https://s3.example.com"
region = ""
path_style = false

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "backup_user"
mysql_pwd = "<provide-securely>"
mysqldump_path = "C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysqldump.exe"
skip_ssl = true

[restore.mysql]
execution_mode = "native"
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "restore_user"
mysql_pwd = "<provide-securely>"
mysql_client_path = "C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysql.exe"
workspace_home = "C:\\Users\\<Username>\\AppData\\Local\\Temp\\ppk-restore-mysql"
allow_restore_to_source_db = false
drop_target_db_before_restore = false
default_check_sql_enabled = true
custom_check_sql_file = ""
keep_workspace_on_success = true
keep_workspace_on_failure = true

Project Profile Description (prj.toml)

This document defines project identification, applied data catalogs, MySQL library name and table filtering rules, and multi-level progressive retention policies for remote backups in object storage.

The number of local historical backups is configured in [public] .history_bak_num of bak.toml.

[local]

[remote.retain]

This section defines retention and cleanup policies for remote backups in object storage. max_get_object_count must be no less than the number of objects that may be retained; for an initial configuration, keep really_remove = false, review the cleanup plan and logs, then explicitly enable actual deletion.

Platform path differences

Fields and retention policies are the same on every operating system; only data_dir uses the local path format.

macOS / Linux：

[local]
prj_key = "my-project"
data_dir = "/srv/myapp/data"
excluded_data_dirs = ["caches", "log", "tmp"]
mysql_db_name = "app_db"
include_table_list = []
exclude_table_list = []

[remote.retain]
max_get_object_count = 100
minimum_retain_count = 3
minimum_retain_date_count = 3
days = [1, 2, 3, 7]
months = 6
years = [1, 2, 3]
really_remove = false

Windows：

[local]
prj_key = "my-project"
data_dir = "C:\\Users\\<Username>\\AppData\\Local\\MyApp\\data"
excluded_data_dirs = ["caches", "log", "tmp"]
mysql_db_name = "app_db"
include_table_list = []
exclude_table_list = []

[remote.retain]
max_get_object_count = 100
minimum_retain_count = 3
minimum_retain_date_count = 3
days = [1, 2, 3, 7]
months = 6
years = [1, 2, 3]
really_remove = false

mysql_bak_request.toml Configuration Manual

mysql_bak_request.toml is the request configuration file for the peppykeep backup mysql-db-list command, used to define the specific parameters of a bulk MySQL backup task.

File Role

• Describe which databases to back up this time
• Define table filter rules per database (include/exclude)
• Specify control parameters for backup behavior (whether to upload, clean, etc.)

Profile Description

This document describes the meaning and setting methods of each parameter in the PeppyKeep backup service configuration file `mysql_bak_request.toml’.

Document Creation Instructions

📝 Important: This profile needs to be created by the user themselves

mysql_bak_request.toml is not automatically generated by the peppykeep tool and needs to be created manually by the user according to the actual backup needs.

Create steps:

1. Create the file under a configuration directory such as/path/to/user/.peppykeep/conf/
2. Refer to the configuration examples in this document and fill in the relevant parameters as needed
3. It is recommended that files be included in version control (Git) for easy tracking of changes

File naming suggestions:

mysql_bak_request.toml          # 默认配置
mysql_bak_request.daily.toml    # 日常备份配置
mysql_bak_request.weekly.toml   # 每周备份配置
mysql_bak_request.prod.toml     # 生产环境配置

Full configuration example

# ============================================================
# Backup job identity
# ============================================================

# Instance id for this project/instance
# Align with prj_key in prj.toml when possible
instance_name = "test_717_file"

# Upload to object storage when true; local-only when false
# Final behavior also depends on bak_location_type in bak.toml
upload_to_oss = true

# Prune local old backups per history_bak_num when true
remove_older_files = true

# Prune remote old backups per remote.retain when true
remove_older_oss_files = true

# ============================================================
# Job metadata
# ============================================================

[base]
# Job UUID; auto-generated when empty
uuid = ""

# Job name for logs and UI
name = "test_mysql_bak"

# Job description
desc = "backup test_717_file databases"

# ============================================================
# Docker container (optional)
# ============================================================

# [container]
# Container name for Docker MySQL; empty uses local mysqldump
# docker_container_name = ""

# Path to docker binary for container backups
# docker_cmd_path = "/usr/local/bin/docker"

# ============================================================
# Database list (core)
# ============================================================

# Database 1: full backup
[[db_config_list]]
# Database to back up
db_name = "ldbak_test"
# Included tables; empty means all
include_table_list = []
# Excluded tables; empty means none
exclude_table_list = []

# Database 2: full backup
[[db_config_list]]
db_name = "test_db_2"
include_table_list = []
exclude_table_list = []

Policy Management

This set of pages addresses three main things:

• What to keep when backing up and what not to put in the backup
• Whether the backup file is stored locally or in an object, how long it is kept, and when it is cleaned up
• After the backup is completed, what are the task results and abnormal status?

This group of pages

• Backup content and exclusion rules
• Storage Location and Retention Rules
• Scheduling & Retention Policies
• Task Results and Common Status

For examples of relevant scenarios, see Applicable Scenarios in the Product Introduction; for command parameters, see Command Reference.

Backup content and exclusion rules

Before the backup, make a clear list of what really needs to be retained, and then decide which directories and files do not enter this backup.

Typical retention requirements include:

• Business Master Data Directory
• Profiles and running configurations
• Supporting files that must be relied upon when restoring
• Required Run Logs or Audit Logs

Typical ones that are not backed up include:

• Temp Directory
• Cache directory
• Build Product
• Data with a separate backup link already exists
• Regeneratable intermediate files

If the file is missing after recovery, first check whether it is not included in the backup, or filtered by the exclusion rule.
If the backup volume is obviously large, first check whether the log directory, cache directory or other content that does not need to be retained for a long time is brought in.

Storage Location and Retention Rules

PeppyKeep does not offer cloud or other managed storage. You will need to select and manage your own local disks, S3 compatible object storage, or other storage scenarios; the storage service’s capacity, availability, retention policies, and issues arising therefrom are not covered by PeppyKeep.

Backup files can be saved locally only, or they can continue to be saved to the object store. Which one to choose depends on recovery speed, retention time and far-end retention requirements.

Local save is better for:

• Rapid recovery required
• Keep only historical files for a shorter period of time
• Check the local file before deciding whether to proceed with the upload

Object storage is better for:

• Need to save offsite
• Needs to be kept longer
• Local retention and remote retention need to be disassembled

When configuring object storage, focus on checking:

• bucket
• prefix
• endpoint
• region

Retention rules need to look at two things at the same time:

• How many historical backups to keep locally
• When to clean up the remote history files separately

backup run --upload does not automatically clean up remote history files.
Remote history files need to be cleaned up separately.

Scheduling and Retention Policies

The backup execution window, the number of historical reservations, and the cleaning rhythm need to be arranged together.

If the tasks are often stacked, see if the execution window is too centralized and the backup range is too large.
If the historical file grows too fast, see if the number of local reservations and the pace of remote cleanup are reasonable first.
If you can’t find a suitable backup point when you need to restore, look back to see if the retention time is too short.

Task Results and Common States

After the backup is completed, look at the task results before deciding on the next step.

Common states include:

• Success: Task completed as scheduled
• Partial success: The task was completed, but some of the content failed or was skipped
• Failure: Task not completed
• Running: Task is still running

Prioritize when you see partial success or failure:

• Whether the source path is accessible
• Whether the output directory or destination location is writable
• Whether the MySQL connection parameters are correct
• Whether the object storage configuration is correct
• Whether the encryption or decryption process is complete

If the task is clearly stacked, look at the execution window, backup scope, and cleaning rhythm first.
If you fail continuously, see which step the failure occurs in first, and then decide whether to retry, adjust the configuration, or use another backup path instead.

Starter

Starter covers the basic path of daily backup and recovery: first select the critical data to be protected, use the configuration template to complete a dry-run, then perform a backup and verify the restore point. When you need to save off-site, configure the second copy or object storage destination.

It is recommended to read in the following order: file or directory backup, MySQL backup, bulk backup, multi-replica and object storage, versioning strategy, and finally validate restore point-based recovery.

File or directory backup: Back up critical data

When the app catalog, profiles, and business files need to be kept together, follow the steps below.

Steps to follow

1. Confirm and modify the directory and file scope to be backed up this time in the bak.toml under the default configuration directory, and confirm that the backup type is application data:

` \toml [public] bak_type = “app_data” bak_location_type = “local” # or local_and_remote

Specify data_dir and exclusion rules in `prj.toml’. See bak.toml and prj.toml for complete fields.

2. Exclude temporary directories, cache directories, build products, and regeneratable intermediate files from this backup.
3. Data that already has a separate backup link will not be repeated in this backup.
4. Perform a check first:

peppykeep backup run --bak-type app-data --config-home /path/to/conf --no-upload

5. Perform a formal backup after checking that everything is correct:

peppykeep backup run --apply --bak-type app-data --config-home /path/to/conf --no-upload

6. When you need to continue saving to the object store, go to Save to object store after local backup.

results verification

• ‘BakType’ is’ AppData `in the pre-check or execute output.
• The directories and files that need to be retained are already in the backup.
• Unwanted directories and files are not brought in together.
• The backup file required for the restore has been generated locally.

Order Details:

• backup run

MySQL Backup: Backing Up Your Database

Follow the steps below when the business library needs to generate backup files daily, hourly, or continuously in a fixed window.

Steps to follow

1. Confirm app.toml, bak.toml, prj.toml exist; tune MySQL, output dir, encryption, and upload in bak.toml. bak.toml must include:

[public]
bak_type = "db"
db_type = "mysql"
bak_location_type = "local"   # or local_and_remote

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "your_user"
mysql_pwd = "your_password"
mysqldump_path = "/path/to/mysqldump"
# skip_ssl = true             # Enable when TLS cert is untrusted

Specify the library name to back up in `prj.toml’:

[local]
prj_key = "your_project"
mysql_db_name = "your_db"

2. When the certificate chain of the target MySQL is not trusted by the local client, it is decided whether to set skip_ssl in combination with the actual environment.
3. Perform a check first to confirm that the connection and configuration can be read normally:

peppykeep backup run --bak-type db --config-home /path/to/conf

4. Perform a formal backup after the output is correct:

peppykeep backup run --apply --bak-type db --config-home /path/to/conf

5. When retaining only local files, explicitly add --no-upload:

peppykeep backup run --apply --bak-type db --config-home /path/to/conf --no-upload

6. When uploading to the object store immediately after this task, explicitly add --upload:

peppykeep backup run --apply --bak-type db --config-home /path/to/conf --upload

results verification

• ‘BakType’ is’ Db `in the pre-check or execute output (or Action indicates a database backup).
• The backup file has been generated at the location specified in the configuration.
• .ppk when not encrypted; .ppke when encryption is on.
• The number of local history files matches this configuration.

When you need to process multiple libraries at once under the same MySQL instance, check Bulk backup of multiple MySQL libraries with the same instance.

Order Details:

• backup run
• cleanup local

Bulk backup of MySQL

If there are multiple libraries under the same MySQL instance that need to be backed up together, and the table filtering rules of each library are not exactly the same, follow the steps below.

Steps to follow

1. Confirm default config dir has app.toml, bak.toml, prj.toml; set [mysql] in bak.toml like single-DB backup.
2. Manually create a mysql_bak_request.toml request file (or JSON) and list the databases that need to be backed up this time.
3. Write include_table_list' or 'exclude_table_list in each database entry when filtering by table is required.
4. Perform a check first to confirm that both the database list and the filtering rules are as expected:

peppykeep backup mysql-db-list --request-file ./mysql_bak_request.toml --config-home /path/to/conf

5. Perform a formal backup after checking that everything is correct:

peppykeep backup mysql-db-list --request-file ./mysql_bak_request.toml --config-home /path/to/conf --apply

results verification

• The Action in the output is backup mysql-db-list ', and the DbCount `matches the number of libraries in the request file.
• The databases that need to be backed up have entered this task.
• The table filter rules for each database match the request file.
• Backup files, upload results and cleanup results are consistent with this configuration.

Order Details:

• backup mysql-db-list

Multi-Replica Backup

Multi-copy backup refers to the same backup task while remaining on different media or different failure domains, such as local disk + object storage/network disk. Multiple copies are not a substitute for recovery verification: each copy should be sampled regularly and confirmed for recovery.

Referral Process

1. First use backup run to generate a backup locally and complete the dry-run check.
2. Make sure the local archive is readable, then use backup upload-artifact to write to the second destination.
3. Perform a backup list-latest check on the remote object for key, size, and modification time.
4. Regularly download a remote copy to perform decryption, unpacking, or recovery drills in a temporary directory.
5. Set retention periods for local and remote to avoid the same failure and delete all replicas at the same time.

notice

• Do not place two copies on the same disk, on the same host, or in the same fault domain.
• The bucket, prefix, endpoint, and region of the object store must be recorded and periodically checked.
• backup run --upload does not automatically clean up remote history files; remote cleanup must be performed separately.

Related: Upload archive, backup download-artifact, cleanup object-storage.

Backup to Object Storage or Network Drive

When the local backup file has been generated and you want to continue saving to the object store or to an S3/WebDAV-compatible disk destination, follow the steps below. The specific available destinations are the current version configuration and ppk --help.

Steps to follow

1. Verify that the local backup file has been generated.
2. Confirm that the object storage related information has been written in the configuration, including bucket, prefix, endpoint, region.
3. Perform the upload:

peppykeep backup upload-artifact --apply --input-file /path/to/backup.ppke --config-home /path/to/conf

4. When remote files need to be sampled, perform a download:

peppykeep backup download-artifact --apply --remote-key project-a/backup.ppke --output-file /tmp/backup.ppke --config-home /path/to/conf

5. When the remote history file needs to be cleaned, execute the clean command separately. The upload action itself does not automatically clean up the remote history file.

results verification

• The remote object is already visible.
• The object naming is consistent with the project identity, prefix settings.
• Downloaded files can be decrypted or reverted directly.

Order Details:

• backup upload-artifact
• backup download-artifact
• Remote History Cleanup

Timeline and versioning policy

Backup policies should be managed for configuration changes and recovery points. Each time a data scope, exclusion rule, encryption key, object storage, or retention policy is adjusted, a new configuration version should be formed and the reason for the change should be preserved.

Recommended Practices

1. Use app.toml, bak.toml, prj.toml, and the necessary request file as a configuration snapshot.
2. Copy the snapshot before modification and record the time, operator, changes, and applicable backup tasks.
3. After the configuration changes, execute dry-run before generating a new backup point; do not overwrite the old configuration or the old backup point.
4. Record the configuration version along with the item identification, time, and remote key of the backup file.
5. When restoring, first select the restore point that matches the target data time, and verify with the corresponding configuration snapshot.

Retention and rollback

Local and remote retention policies should be set separately and at least one historical version validated for recovery should be retained. Before rolling back the configuration, perform it in the test directory to confirm that the path, permissions, key, and object storage destination are available.

The timeline policy is used in conjunction with the scheduling and retention policy. For the actual command, see Command Reference.

Restore from restore point

When a file is deleted by mistake, the configuration is changed by mistake, or you need to review the contents of the historical version, follow the steps below.

Steps to follow

1. First select the backup point that you want to restore.
2. When the backup file is in the object store, first download it locally:

peppykeep backup download-artifact --apply --remote-key project-a/backup.ppke --output-file /tmp/backup.ppke --config-home /path/to/conf

3. When the backup file is.ppke, first decrypt it as.ppk:

ppk decrypt --input /tmp/backup.ppke --output /tmp/backup.ppk --apply --config-home /path/to/conf

4. Restore the required files or directories to a temporary location first, do not overwrite the production path directly.
5. After checking the file contents, directory structure and permissions, replace the official file or directory.

results verification

• The retrieved files are as expected.
• The directory structure is correct.
• Permissions and owners meet the requirements of the target environment.

Order Details:

• backup download-artifact
• ppk decrypt

Advanced

Advanced covers scenarios that require more security, scale, or continuity: encrypted backups, volumetric backups of oversized files or directories, and regular recovery drills.

All advanced processes should first dry-run in an independent test environment before performing and documenting recovery results, time consuming, and dependencies.

Encrypted backups

It is necessary to prevent the backup archive from being unauthorized to read, encrypt the backup with the public key, and separate the recovery private key from the backup node.

Recommended process:

1. Use ppk key generate to generate the key pair.
2. Configure only the public key in the backup configuration, first perform a dry-run check of inputs, outputs, and destinations.
3. Perform a backup and confirm the generation of the .ppke file.
4. Private keys are kept in an independent recovery environment, and decryption and recovery exercises are performed regularly.

See Encryption and Decryption for the parameters and compatible formats of the encryption archive. Do not write private key passwords to configurations, scripts, or tickets.

Extra large file or directory backups

When the directory volume has exceeded the applicable scope of a single archive file, follow the steps below.

Steps to follow

1. Determine the volume size and local task directory planning first.
2. Perform a Volume Backup:

peppykeep backup large-dir run --apply --config-home /path/to/conf --data-dir /path/to/large-dir --project-key project-a --chunk-size 4GiB

3. To view the status of a recent task:

peppykeep backup large-dir list --config-home /path/to/conf --project-key project-a --top 10

4. Verify Local Task Structure and Volume Files:

peppykeep backup large-dir verify --config-home /path/to/conf --project-key project-a

5. When recovery is required, perform a recovery from the local task directory:

peppykeep backup large-dir restore --config-home /path/to/conf --project-key project-a --output-dir /path/to/restore-out

backup large-dir restore relies on local task directories and volume files. If the local partition is missing, complete the local file before performing the recovery.

results verification

• Task status is complete.
• The scrolling file is complete, and the verification is passed.
• Restore output directory as expected.

Order Details:

• backup large-dir

Recovery Drill

Use a standalone ppk drill mysql to drill down in an isolated environment when you need to confirm that the backup files, decryption process, SQL import and recovery process are still working properly. This command is not equivalent to production restoration, nor does it overwrite the production library by default.

Steps to follow

1. Select a real backup point and prepare the test environment.
2. When the backup file is in the object store, first download it locally:

peppykeep backup download-artifact --apply --remote-key project-a/backup.ppke --output-file /tmp/backup.ppke --config-home /path/to/conf

3. When the backup file is an encrypted file, complete the decryption first:

ppk decrypt --input /tmp/backup.ppke --output /tmp/backup.ppk --apply --config-home /path/to/conf

4. First, execute dry-run to confirm the walkthrough library, workspace, private key, and validate SQL:

ppk drill mysql --project-key project-a --backup-file /tmp/backup.ppke --target-db-name ppk_drill_project_a --config-home /path/to/conf

5. After confirmation, add --apply, and the CLI will automatically decrypt, unpack, import SQL, and generate a walkthrough report.
6. Check that critical directories, critical files, and critical data are fully available and document the time-consuming and additional dependencies of this restore.

results verification

• Critical directories and critical data have been restored successfully.
• Private keys, passwords, and recovery environments are all available for use during the walkthrough.
• The new dependencies and processing steps added in this walkthrough have been documented.

Order Details:

• backup download-artifact
• ppk decrypt
• ppk drill mysql

Backup Policy

Backup policies are used to unify the management of backup times, recoverable versions, and storage space. It is recommended to define a timeline before configuring retention quantities and automatic cleanup rules, and periodically verify that restore points are available.

Define timeline, configure scheduling

Determine the frequency of backups, execution windows, and recovery point intervals based on the frequency of data changes and acceptable data loss windows. The execution window should avoid business peaks and allow sufficient time for database export, compression, encryption, and upload.

Each time the data range, backup destination, or scheduling plan is adjusted, the configuration version, reason for the change, and effective time should be recorded. After the configuration changes, first execute dry-run, and then create a new backup point.

Configure the number of versions, reserve the restore point

Set the number of reserved versions for local and remote, respectively, and reserve at least one historical restore point that has completed recovery verification. The reserved quantity shall cover the daily misoperation recovery, recent failure recovery and longer term business traceability requirements.

Backup files, configuration snapshots, and validation reports should correspond to the same timeline; when restoring, select a restore point that matches the target data time, not just guess the version by file name.

Automatic cleaning to avoid wasted space

Historical files stored locally and on objects should be cleaned up in accordance with their respective retention policies. Before cleaning, execute dry-run to confirm the target path, project identification, prefix, and quantity to be deleted; use --apply after confirming that it is correct.

backup run --upload does not automatically clean up remote history files, remote cleanup requiresppk cleanup object-storageto be performed separately. Alarms should be retained and storage quotas checked when a cleanup fails, and backup or recovery issues cannot be masked by shortening the retention period.

Detailed scheduling and retention rules are available in Scheduling and Retention Policies and Configure Timeline and Versioning Policies.

Universal app backup & restore

This group is for business systems consisting of databases, profiles, and application catalogs. First, confirm the backup boundary between the application data and the database, and then verify the recovery order and dependencies in an independent environment.

MySQL-based business systems

MySQL-based business systems typically include a database, upload files, application configuration, and run dependencies. Database backups are not a substitute for app catalog backups; they must also be validated in dependency order when restored.

This group provides two entrances to the general application system backup and recovery drill.

Universal application backup

For MySQL-based business systems, it is recommended that the following be included in the same reviewable backup plan: MySQL database, app upload directory, app configuration, and dependency instructions required for recovery.

Execution Order

1. Back up application files and configurations using file or directory backups.
2. Back up your business database using MySQL Backup.
3. Record the configuration version, project identification, and time window of the two types of backups to avoid database and file from different restore points.
4. Execute dry-run separately in the test environment, and complete an application launch, key query, and key file read verification.

When restoring, you should first prepare independent databases and application catalogs, then restore them in the order of application dependency, and finally perform a full functional check.

Recovery Drill

For MySQL-based business systems, use ppk drill mysql to perform a recovery drill in an isolated environment. The walkthrough should validate the database, application files, configuration, and startup dependencies at the same time, rather than just confirming that the backup files can be decrypted.

1. Prepare separate MySQL target libraries and application directories in an isolated environment.
2. Select the database and file restore points on the same timeline, and execute ppk drill mysql dry-run first.
3. After confirming the independent exercise library and workspace, add --apply to complete decryption, unpacking, SQL import and verification.
4. Verify database tables, critical business records, upload files, configuration references, and app launch.
5. Document recovery time, missing dependencies, permission issues, and steps that need to be handled manually.

See Recovery Drill for general recovery process and restore mysql for MySQL target library security constraints.

Dedicated app backup & restore

This group is used for applications with proprietary asset models, filtering rules, or synchronous semantics. They should not apply the common file backup process directly, but should first review the asset plan and override report.

The PeppyKeep team is actively developing more proprietary application backup capabilities. If you have a specific need, you are welcome to collate the statement of need and submit it through Contact Support and we will evaluate the support plan accordingly.

Work Asset Backup & Sync

Work Asset Capabilities are targeted at dotfiles, developer tool configurations, lightweight application states, and other configurable work assets using the Scan → Review → Plan for → Verification → → Recovery Preview Recovery process.

ppk work-assets scan --home /path/to/home --asset-set-key default
ppk work-assets apply --asset-set-key default --apply
ppk work-assets verify --asset-set-key default
ppk work-assets restore preview --asset-set-key default

Sensitive assets, insufficient permissions, exclusions, and pending items in the plan must be visible to the user and cannot be silently entered into the backup. See Working Asset Backup for complete command parameters.

Windows User Manual

Configure Folders

After install, %USERPROFILE%\.peppykeep\conf gets app.toml, bak.toml, and prj.toml. Before the first backup, confirm they exist and match your environment (MySQL, paths, object storage). Bulk MySQL jobs also need mysql_bak_request.toml.

Field reference: Configuration files (app.toml, bak.toml, prj.toml, etc.). Use --config-home or env var PPK for the config directory.

Quick Start (Basic Application Data Backup)

In cmd:

REM1. Confirm that the download and installation have been completed on the official website

REM2. Confirm that app.toml, bak.toml, prj.toml already exists under % USERPROFILE %\ .peppykeep\ conf and modify it by environment (e.g. data_dir of prj.toml)

REM3. Prepare test data
mkdir %TEMP%\test_file_717
echo sample > %TEMP%\test_file_717\sample.txt

REM4. Pre-inspection
peppykeep backup run --config-home %USERPROFILE%\.peppykeep\conf --bak-type app-data

REM5. Official backup (local + upload, configured by bak.toml)
peppykeep backup run --apply --config-home %USERPROFILE%\.peppykeep\conf --bak-type app-data

’–no-upload` can only be added when backing up locally.

Download & Install

Go to the PeppyKeep official website download page to download and install

Function elements

Follow the scenario step by step, each section contains configuration points, dry-run and formal execution (--apply):

Function block index

Configuration Specification (CS)

The following files are automatically generated in the default configuration directory during installation. Please confirm that the files exist before modifying them:

• app.toml
• bak.toml
• prj.toml

Windows Download and Installation

Go to the PeppyKeep official website download page to download and install

This manual does not repeat the maintenance and installation steps. Once the installation is complete, read the Windows user manual to configure and perform the first backup.

First Backup

Please complete the download and installation on the PeppyKeep official website download page first. This page only describes the first backup after the installation is complete.

1. Confirm %USERPROFILE%\.peppykeep\conf contains installer-generated app.toml, bak.toml, and prj.toml, updated for your environment
2. Prepare test data (optional):

mkdir %TEMP%\test_file_717
echo sample content > %TEMP%\test_file_717\sample.txt

3. Pre-test (dry-run, no backup file):

peppykeep backup run --config-home %USERPROFILE%\.peppykeep\conf

4. After confirming that the output is correct, formally execute:

peppykeep backup run --apply --config-home %USERPROFILE%\.peppykeep\conf

Examples of pre-check outputs (subject to reference configuration):

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : C:\Users\admin\AppData\Local\Temp\test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

Only dry-run without `--apply’. The first execution may trigger a device binding login, please complete the authorization before the timeout.

Windows capabilities

The following sections demonstrate using the reference configuration % USERPROFILE %\ .peppykeep\ conf to complete common operations on Windows. Each section is recommended to be formally executed by first dry-run followed by --apply.

Function blocks are organized hierarchically by Official Website Pricing.

Accounts & General

Shared across plans, not sold separately.

Основні функції

Encryption and recovery features

Notification

Universal Sense Backup

Dedicated Aware Backup

Accounts & General

The features in this section are not sold separately with the subscription plan and are available to all Windows users.

Returns the Windows function block index

Theme My Login Action

When the backup/restore command is executed for the first time, if the device is not already bound locally, the CLI pauses and prompts to complete the authorization in the browser. You can also take the initiative to execute the login command.

View Version

peppykeep --version

Example output:

peppykeep 26.7.836+20260716152959

Login (using cached credentials)

peppykeep login --config-home %USERPROFILE%\.peppykeep\conf

When logged in and the credentials are valid:

Action = auth login
Status = SUCCESS
AuthState = CACHED

Refresh Login/Device Bindings

When you need to rebind or refresh the authorization:

peppykeep login --refresh --config-home %USERPROFILE%\.peppykeep\conf

Example output:

Action = auth login
Status = REQUIRED
OpenUrl = https://www.peppykeep.com/console/device/binding?auth_session_id=...
ManualCodeUrl = https://www.peppykeep.com/console/device/code/
DeviceCode = XXXX-XXXX-XXXX-XXXX

Follow these steps to bind this device:

1. Open this link in your desktop browser
   https://www.peppykeep.com/console/device/code/

   Or open official site:
   Login -> Console -> Devices -> Bind a new device

2. Enter this device code
   XXXX-XXXX-XXXX-XXXX

Waiting for device authorization...
Status = AUTHORIZED

Action = auth login
Status = SUCCESS
AuthState = LOGGED_IN
CachePath = C:\Users\admin\.peppykeep\auth\license_bundle.enc

Once the binding is complete, the interrupted backup/restore command will continue to execute automatically. Do not share DeviceCode with others.

Backup pre-test function

Only dry-run ⚠️ without --apply, no backup file will be written. The first execution may trigger the device binding login, please complete the authorization before the timeout.

Pre-check command

peppykeep backup run --config-home %USERPROFILE%\.peppykeep\conf

Sample Normal Output

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : C:\Users\admin\AppData\Local\Temp\test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

Order Details Reference

• Click for command details

Основні функції

The basic data backup includes unencrypted backups, universal MySQL application-aware unencrypted backups, basic recovery, execution history and version browsing, etc.; see the following function page for object storage upload download and retention policy cleaning.

Returns the Windows function block index

Basic Application Data Backup

This article demonstrates backing up app catalog files on Windows, using the reference configuration directory % USERPROFILE %\ .peppykeep\ conf as an example. It is recommended to dry-run (without --apply) every step before formally executing.

Prepare test data

In cmd:

mkdir %TEMP%\test_file_717
echo sample content > %TEMP%\test_file_717\sample.txt

Backup to local

enforce_provisioning_action

1. app.toml — 详见 app.toml 配置说明

2. bak.toml — Key Fragments (local, non-encrypted examples only):

[public]
bak_type = "app_data"
bak_location_type = "local"
history_bak_num = 3
log_level = "INFO"
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\logs\\peppykeep"
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\backup\\peppykeep"
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\.peppykeep_tmp"
max_bak_queue_size = 1

[backup_encryption]
enabled = false

完整参数见 bak.toml 配置说明。

3. prj.toml — Key Fragments:

[local]
prj_key = "test_717_file"
data_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\test_file_717"

详见 prj.toml 配置说明。

Perform the preliminary checks: §.

peppykeep backup run --config-home %USERPROFILE%\.peppykeep\conf --bak-type app-data

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : C:\Users\admin\AppData\Local\Temp\test_file_717
Location   : Local
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Perform a backup

peppykeep backup run --apply --config-home %USERPROFILE%\.peppykeep\conf --bak-type app-data

Example output on success:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : C:\Users\admin\AppData\Local\Temp\test_file_717
Location     : Local
Force        : false
Artifact     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260702_112737.ppk
ArtifactSize : 291 B
Status       : Command completed successfully.

Product extension: unencrypted as.ppk; .ppke 'when [backup_encryption] enabled = true `is enabled.

Backup to local and upload object store

When bak_location_type = "local_and_remote" and [object_storage] enabled = true in ’bak.toml`, the object storage is automatically uploaded after the backup is completed.

enforce_provisioning_action

bak.toml Key Fragments (S3 compatible storage example):

[public]
bak_type = "app_data"
bak_location_type = "local_and_remote"
history_bak_num = 3
log_level = "INFO"
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\logs\\peppykeep"
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\backup\\peppykeep\\test_717_file"
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\.peppykeep_tmp"
max_bak_queue_size = 1

[object_storage]
enabled = true
provider = "s3"
bucket = "VoosTestBucket"
prefix = ""
endpoint = "https://s3.ca-east-006.backblazeb2.com"
region = "ca-east-006"
access_key_id = "<YOUR_ACCESS_KEY_ID>"
access_key_secret = "<YOUR_ACCESS_KEY_SECRET>"
path_style = true

[backup_encryption]
enabled = true
algorithm = "aes-256-gcm"
key_wrap_algorithm = "x25519"
public_key_file = "C:\\Users\\admin\\AppData\\Local\\Temp\\key\\ppk.pub"
delete_plain_after_encrypt = true

Perform the preliminary checks: §.

peppykeep backup run --config-home %USERPROFILE%\.peppykeep\conf --bak-type app-data

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : C:\Users\admin\AppData\Local\Temp\test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

Perform a backup

peppykeep backup run --apply --config-home %USERPROFILE%\.peppykeep\conf --bak-type app-data

Example output on success:

[1/5] Prepare local workspace
[2/5] Copy application data
[3/5] Create and encrypt backup artifact
Encryption progress: 100% (292 B/292 B)
[4/5] Upload artifact to object storage
=== Upload Target ===
Provider  : s3
Bucket    : VoosTestBucket
RemoteKey : test_717_file/test_717_file-bak_20260730_114555.ppke
Target    : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260730_114555.ppke
[5/5] Apply local retention policy
=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : C:\Users\admin\AppData\Local\Temp\test_file_717
Location     : LocalAndRemote
Force        : false
Artifact     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file\test_717_file-bak_20260730_114555.ppke
ArtifactSize : 456 B
Bucket       : VoosTestBucket
RemoteKey    : test_717_file/test_717_file-bak_20260730_114555.ppke
Provider     : s3
Target       : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260730_114555.ppke
LocalCleanup : applied
Status       : Command completed successfully.

Local Only, No Upload (Temporary Override)

When configured to local_and_remote but only want to keep local this time:

peppykeep backup run --apply --config-home %USERPROFILE%\.peppykeep\conf --bak-type app-data --no-upload

Order Details Reference

• backup run command description

Database backup

Backup to local

enforce_provisioning_action

1. app.toml

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\log\\peppykeep"

# Log file name (full path: C:\\Users\\admin\\AppData\\Local\\Temp\\log\peppykeep\app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml

# Backup type: database
bak_type = "db"

# Backups are also saved locally
bak_location_type = "local"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"

# Local backup root C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"

# Local temp workspace C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

[mysql]
Database Host
mysql_ip = "localhost"
Database Port
mysql_port = 3306
Databse username
mysql_user_name = "ldbak_test"
Database Pass
mysql_pwd = "123456"
# mysqldump tool path
mysqldump_path = "/usr/local/bin/mysqldump"
# Docker Command Path (for containerized backups)
docker_cmd_path = "/usr/local/bin/docker"

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

[mysql]
mysql_ip = "localhost"
mysql_port = 3306
mysql_user_name = "root"
mysql_pwd = "root"
# mysqldump tool path
mysqldump_path = "C:\\PROGRA~1\\MySQL\\MYSQLS~1.0\\bin\\mysqldump.exe"
skip_ssl = true
# docker_container_name = "non-exists-name" # When commenting on this line (None), the local mysqldump command is used, otherwise the docker exec command will be executed
# Docker Command Path (for containerized backups)
docker_cmd_path = "/usr/bin/docker"

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "C:\\test_data"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# Database Backup Precheck
peppykeep backup run --bak-type db --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\data
Location   : Local
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Performing a Database Backup

peppykeep backup run --apply --bak-type db --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action   : backup run
Project  : test_717_file
BakType  : Db
DataDir  : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\data
Location : Local
Force    : false
Artifact : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\backup\test_717_file\test_717_file-bak_20260703_103517.ppk
Status   : Command completed successfully.

Result

Backup to Object Storage

enforce_provisioning_action

1. app.toml

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\log\\peppykeep"

# Log file name (full path: C:\\Users\\admin\\AppData\\Local\\Temp\\log\\peppykeep/app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml (S3 as an example)

# Backup type: database
bak_type = "db"

# Backups are also saved locally
bak_location_type = "local_and_remote"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"

# Local backup root C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"

# Local temp workspace C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

# Enable Object Storage
[object_storage]
enabled = true

# Using S3 protocol (Backblaze B2 compatible)
provider = "s3"

# Bucket Name
bucket = "TestBucket"

# Object key prefix (like folder path)
prefix = "test_local"

# S3 Compatible Endpoints (Backblaze B2 + East)
endpoint = "https://s3.xxxxxxxxxxxxxx.com"

Region
region = "ca-east-006"

Access Key ID
access_key_id = "xxxxxxxxxxxxxx"

Access key
access_key_secret = "xxxxxxxxxxxxxx"

# Use path style URL (bucket/object instead of web hosting style)
path_style = true

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "C:\\test_data"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# Database Backup Precheck
peppykeep backup run --bak-type db --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\data
Location   : LocalAndRemote
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Performing a Database Backup

peppykeep backup run --apply --bak-type db --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : Db
DataDir      : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\data
Location     : LocalAndRemote
Force        : false
Artifact     : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\backup\test_717_file\test_717_file-bak_20260703_112245.ppk
Bucket       : VoosTestBucket
RemoteKey    : test_local_voos/test_717_file/test_717_file-bak_20260703_112245.ppk
Provider     : s3
Target       : s3://VoosTestBucket/test_local_voos/test_717_file/test_717_file-bak_20260703_112245.ppk
LocalCleanup : applied
Status       : Command completed successfully.

Result

Order Details Reference

• Click for command details

Docker Backup

Backup to local

enforce_provisioning_action

1. app.toml

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\log\\peppykeep"

# Log file name (full path: C:\\Users\\admin\\AppData\\Local\\Temp\\log\\peppykeep/app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml

# Backup type is docker backup
bak_type = "db_and_app_data"

# Backups are also saved locally
bak_location_type = "local"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"

# Local backup root C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"

# Local temp workspace C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "root"
mysql_pwd = "root"
# mysqldump tool path
mysqldump_path = "/usr/bin/mysqldump"
skip_ssl = true
docker_container_name = "ppk-mysql-test"
docker_cmd_path = "C:\\Users\\admin\\AppData\\Local\\Programs\\DockerDesktop\\resources\\bin\\docker.exe"

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "C:\\test_data"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# docker Backup Precheck (Database + App Catalog)
peppykeep backup run --bak-type db-and-app-data --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : DbAndAppData
DataDir    : C:\test_data
Location   : Local
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Perform a docker backup

peppykeep backup run --bak-type db-and-app-data --apply --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : DbAndAppData
DataDir      : C:\test_data
Location     : Local
Force        : false
Artifact     : C:\\Users\\admin\\AppData\\Local\\Temp\\backup\\peppykeep\\test_717_file\\test_717_file-bak_20260730_111043.ppk
ArtifactSize : 1.2 KiB
Encrypted    : false
UploadTarget : <none>
Status       : Command completed successfully.

Result

Backup to Object Storage

enforce_provisioning_action

1. app.toml

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\log\\peppykeep"

# Log file name (full path: C:\\Users\\admin\\AppData\\Local\\Temp\\log\\peppykeep/app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml

# Backup type is docker backup
bak_type = "db_and_app_data"

# Backups are also saved locally
bak_location_type = "local_and_remote"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log directory C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"

# Local backup root C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"

# Local temp workspace C:\\Users\\admin\\AppData\\Local\\Temp (subdirectories allowed)
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "root"
mysql_pwd = "root"
# mysqldump tool path
mysqldump_path = "/usr/bin/mysqldump"
skip_ssl = true
docker_container_name = "ppk-mysql-test"
docker_cmd_path = "C:\\Users\\admin\\AppData\\Local\\Programs\\DockerDesktop\\resources\\bin\\docker.exe"

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "C:\\test_data"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# docker Backup Precheck (Database + App Catalog)
peppykeep backup run --bak-type db-and-app-data --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : DbAndAppData
DataDir    : C:\test_data
Location   : LocalAndRemote
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Perform a docker backup

peppykeep backup run --bak-type db-and-app-data --apply --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : DbAndAppData
DataDir      : C:\test_data
Location     : LocalAndRemote
Force        : false
Artifact     : C:\\Users\\admin\\AppData\\Local\\Temp\\backup\\peppykeep\\test_717_file\\test_717_file-bak_20260730_113436.ppk
ArtifactSize : 1.2 KiB
Encrypted    : false
Provider     : s3
Bucket       : VoosTestBucket
RemoteKey    : test_717_file/test_717_file-bak_20260730_113436.ppk
UploadTarget : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260730_113436.ppk
LocalCleanup : applied
Status       : Command completed successfully.

Result

Batch Backup Database

Multiple libraries need to be backed up at once under the same MySQL instance, and the filtering rules of each library table may be different. Use mysql_bak_request.toml with backup mysql-db-list.

Backup to local

enforce_provisioning_action

1. bak.toml — need to include MySQL connection and local path (bak_type has no effect on mysql-db-list but [mysql] is required):

[public]
bak_location_type = "local"
history_bak_num = 3
log_level = "DEBUG"
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"
max_bak_queue_size = 1

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "root"
mysql_pwd = "root"
mysqldump_path = "C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysqldump.exe"
skip_ssl = true

完整参数见 bak.toml 配置说明。

2. mysql_bak_request.toml

instance_name = "test_717_file11111"
upload_to_oss = false
remove_older_files = true
remove_older_oss_files = false   # Must be false when upload_to_oss is false

[base]
uuid = ""
name = "batch-mysql-task"
desc = "backup multiple databases"

[[db_config_list]]
db_name = "7.12database1"
include_table_list = []
exclude_table_list = []

[[db_config_list]]
db_name = "7.12database2"
include_table_list = []
exclude_table_list = []

See mysql_bak_request.toml for details.

Perform the preliminary checks: §.

peppykeep backup mysql-db-list ^
  --request-file %USERPROFILE%\.peppykeep\conf\mysql_bak_request.toml ^
  --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action        : backup mysql-db-list
RequestFile   : C:\Users\admin\.peppykeep\conf\mysql_bak_request.toml
Instance      : test_717_file11111
DbCount       : 2
Upload        : false
LocalCleanup  : true
RemoteCleanup : false
Docker        : <none>
Next          : Re-run with --apply to execute.

Perform a backup

peppykeep backup mysql-db-list ^
  --request-file %USERPROFILE%\.peppykeep\conf\mysql_bak_request.toml ^
  --apply ^
  --config-home %USERPROFILE%\.peppykeep\conf

Example output on success:

=== Completed ===
Action        : backup mysql-db-list
RequestFile   : C:\Users\admin\.peppykeep\conf\mysql_bak_request.toml
Instance      : test_717_file11111
DbCount       : 2
Upload        : false
LocalCleanup  : true
RemoteCleanup : false
Docker        : <none>
Status        : Command completed successfully.

Backup to Object Storage

在 mysql_bak_request.toml 中设置 upload_to_oss = true，并在 bak.toml 配置 [object_storage]。上传与保留策略见 备份文件上传对象存储 与 bak.toml 说明。

Order Details Reference

• backup mysql-db-list

Windows Remote Backup Download

Download an existing backup file from the object store to your local

enforce_provisioning_action

1. bak.toml (S3 as an example)

# Enable Object Storage
[object_storage]
enabled = true

# Using S3 protocol (Backblaze B2 compatible)
provider = "s3"

# Bucket Name
bucket = "TestBucket"

# Object key prefix (like folder path)
prefix = "test_local"

# S3 Compatible Endpoints (Backblaze B2 + East)
endpoint = "https://s3.xxxxxxxxxxxxxx.com"

Region
region = "ca-east-006"

Access Key ID
access_key_id = "xxxxxxxxxxxxxx"

Access key
access_key_secret = "xxxxxxxxxxxxxx"

# Use path style URL (bucket/object instead of web hosting style)
path_style = true

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# Database Backup Precheck
peppykeep backup download-artifact --remote-key test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk --output-file C:\\Users\\admin\\AppData\\Local\\Temp\\test\\testdb.ppk --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action         : backup download-artifact
RemoteKey      : test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk
Output         : C:\\Users\\admin\\AppData\\Local\\Temp\\test\\testdb.ppk
Bucket         : VoosTestBucket
Provider       : s3
RestoreArchive : false
Wait           : false
RestoreDays    : 1
WaitTimeout    : 1800
PollInterval   : 30
Next           : Re-run with --apply to execute.

Result

Perform a backup

Performing a Database Backup

peppykeep backup download-artifact --remote-key test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk --output-file C:\\Users\\admin\\AppData\\Local\\Temp\\test\\testdb.ppk --apply --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action         : backup download-artifact
RemoteKey      : test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk
Output         : C:\\Users\\admin\\AppData\\Local\\Temp\\test\\testdb.ppk
Bucket         : VoosTestBucket
Provider       : s3
RestoreArchive : false
Resumed        : false
Written        : 0
TotalSize      : 1186
Status         : Command completed successfully.

Result

Order Details Reference

• Click for command details

Backup File Upload Object Storage

enforce_provisioning_action

[object_storage]
enabled = true
provider = "s3"
bucket = "VoosTestBucket"
prefix = ""
endpoint = "https://s3.ca-east-006.backblazeb2.com"
region = "ca-east-006"
access_key_id = "<YOUR_ACCESS_KEY_ID>"
access_key_secret = "<YOUR_ACCESS_KEY_SECRET>"
path_style = true

Perform the preliminary checks: §.

peppykeep backup upload-artifact --input-file "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_100725.ppk" --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action    : backup upload-artifact
Input     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_100725.ppk
Bucket    : VoosTestBucket
RemoteKey : test_717_file/test_717_file-bak_20260717_100725.ppk
Provider  : s3
Target    : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260717_100725.ppk
Next      : Re-run with --apply to execute.

Performing an upload

peppykeep backup upload-artifact --input-file "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_100725.ppk" --apply --config-home %USERPROFILE%\.peppykeep\conf

On success, the output is as follows:

=== Completed ===
Action    : backup upload-artifact
Input     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_100725.ppk
Bucket    : VoosTestBucket
RemoteKey : test_717_file/test_717_file-bak_20260717_100725.ppk
Provider  : s3
Target    : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260717_100725.ppk
Status    : Command completed successfully.

Order Details Reference

• backup upload-artifact

Delete local old backup files

enforce_provisioning_action

1.prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local Data Storage Directory
data_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\test_file_717" 

2.bak.toml

[public]
# Keep last 3 historical backups locally
history_bak_num = 1

# 日志目录：放在 Temp 下的 my_test_peppykeep
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"

# 备份产出目录
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"

# 临时目录（必须符合规则）
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

Perform the preliminary checks: §.

Open Terminal Execution

peppykeep cleanup local --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action  : cleanup local
Project : test_717_file
Force   : false
Next    : Re-run with --apply to execute.

Result

Delete execution

Delete local old backups

peppykeep cleanup local --apply --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action  : cleanup local
Project : test_717_file
Force   : false
Status  : Command completed successfully.

Result

Order Details Reference

• Click for command details

Delete remote old backup files

Purge historical backups in the object store according to the [remote.retain] policy in ‘prj.toml’. For the first time, it is recommended to keep really_remove = false for analysis only, and then change it to true after confirmation.

enforce_provisioning_action

参考 bak.toml 中的 [object_storage] 与 prj.toml 中的 [remote.retain]。

Field Key

` \toml

prj.toml

[local] prj_key = “test_717_file”

[remote.retain] really_remove = false # Analysis only for the first time; change to true after confirmation

Perform the preliminary checks: §.

peppykeep cleanup object-storage --config-home %USERPROFILE%\.peppykeep\conf

Example output:

=== Dry Run ===
Action  : cleanup object-storage
Project : test_717_file
Force   : false
Next    : Re-run with --apply to execute.

Delete execution

peppykeep cleanup object-storage --force --apply --config-home %USERPROFILE%\.peppykeep\conf

Example of successful output:

=== Completed ===
Action  : cleanup object-storage
Project : test_717_file
Force   : true
Status  : Command completed successfully.

Order Details Reference

• Click for command details

mysql database recovery

enforce_provisioning_action

Perform the preliminary checks: §.

peppykeep restore mysql --backup-file "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_112858.ppk" --target-db-name remote_user --config-home %USERPROFILE%\.peppykeep\conf

=== Dry Run ===
Action            : restore mysql
Project           : test_717_file
SourceDb          : ldbak_test
InputSource       : local_file
BackupFile        : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_112858.ppk
TargetDb          : remote_user
Workspace         : C:\Users\admin\AppData\Local\Temp\ppk-restore-mysql/test_717_file/20260717_113200
ExecutionMode     : native
ContainerRuntime  : <none>
ContainerName     : <none>
MysqlHost         : 192.0.2.10
MysqlPort         : 3306
MysqlClient       : C:\mysql\mysql-9.7.1-winx64\mysql-9.7.1-winx64\bin\mysql.exe
DropTargetDb      : false
ConfirmTargetDb   : <none>
DecryptPrivateKey : <configured restore_encryption.private_key_file>
PromptPassphrase  : false
CheckSqlFile      : <none>
CleanWorkspace    : false
KeepWorkspace     : true
Next              : Re-run with --apply to execute.

Perform a restore.

Perform application data or database backups

peppykeep restore mysql --backup-file "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_112858.ppk" --target-db-name remote_user --apply --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Completed ===
Action           : restore mysql
Project          : test_717_file
SourceDb         : ldbak_test
InputSource      : local_file
TargetDb         : remote_user
BackupFile       : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_112858.ppk
Archive          : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_112858.ppk
SqlFile          : C:\Users\admin\AppData\Local\Temp\ppk-restore-mysql/test_717_file/20260717_113133\extracted\ppk_data\sql\test_717_file_export.sql
Workspace        : C:\Users\admin\AppData\Local\Temp\ppk-restore-mysql/test_717_file/20260717_113133
WorkspaceRemoved : false
Status           : Command completed successfully.

Order Details Reference

• View ppk decrypt command details

Encryption and recovery features

Provide encrypted backup and recovery, oversized directory volume, disaster recovery drill and other capabilities.

Returns the Windows function block index

Extra Large Directory Volume Archive Backup

The extra large directory usesbackup large-dir, which is independent ofbak_typein bak.toml '; you need to configure local_tmp_home , optional [object_storage] , and specify data_dir in prj.toml `.

Backup to local

enforce_provisioning_action

1.prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local Data Storage Directory
data_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\data"

2.bak.toml

[public]

# Backups are also saved locally
bak_location_type = "local"

# Keep last 3 historical backups locally
history_bak_num = 3

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# 日志目录：放在 Temp 下的 my_test_peppykeep
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"

# 备份产出目录
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"

# 临时目录（必须符合规则）
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

Perform the preliminary checks: §.

Open Terminal Execution

peppykeep backup large-dir run --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

Action      : backup large-dir run
Project     : test_717_file
DataDir     : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\data
ChunkSize   : 4.0 GiB
Compression : none
Upload      : false
Resume      : false
TaskRoot    : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp/tasks
Next        : Re-run with --apply to execute.

Result

Perform a backup

Performing Extra Large Directory Volume Archive Backups

peppykeep backup large-dir run --apply --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action           : backup large-dir run
TaskId           : 1784010973296
TaskDir          : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp\tasks\test_717_file-1784010973296
Manifest         : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp\tasks\test_717_file-1784010973296\manifest.json
State            : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp\tasks\test_717_file-1784010973296\state.json
FileCount        : 0
TotalSize        : 0 B
Parts            : 0
ChunkSize        : 4.0 GiB
Compression      : none
Upload           : false
ManifestUploaded : false
Status           : Command completed successfully.

Result

Backup to Object Storage

enforce_provisioning_action

1.prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local Data Storage Directory
data_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\data"

2.bak.toml

[public]

# Save backups both locally and remotely
bak_location_type = "local_and_remote"

# Keep last 3 historical backups locally
history_bak_num = 3

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# 日志目录：放在 Temp 下的 my_test_peppykeep
log_dir = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\logs"

# 备份产出目录
local_bak_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\backup"

# 临时目录（必须符合规则）
local_tmp_home = "C:\\Users\\admin\\AppData\\Local\\Temp\\my_test_peppykeep\\.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

Perform the preliminary checks: §.

Open Terminal Execution

peppykeep backup large-dir run --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action      : backup large-dir run
Project     : test_717_file
DataDir     : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\data
ChunkSize   : 4.0 GiB
Compression : none
Upload      : true
Resume      : false
TaskRoot    : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp/tasks
Next        : Re-run with --apply to execute.

Result

Perform a backup

Performing Extra Large Directory Volume Archive Backups

peppykeep backup large-dir run --apply --config-home %USERPROFILE%\.peppykeep\conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action           : backup large-dir run
TaskId           : 1784011083252
TaskDir          : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp\tasks\test_717_file-1784011083252
Manifest         : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp\tasks\test_717_file-1784011083252\manifest.json
State            : C:\Users\admin\AppData\Local\Temp\my_test_peppykeep\.tmp\tasks\test_717_file-1784011083252\state.json
FileCount        : 0
TotalSize        : 0 B
Parts            : 0
ChunkSize        : 4.0 GiB
Compression      : none
Upload           : true
ManifestUploaded : true
Status           : Command completed successfully.

Result description (S3 as an example)

Order Details Reference

• Click for command details

Basic application and database general encryption backup

Backup to local

enforce_provisioning_action

1.bak.toml

bak_location_type = "local"

[object_storage]
enabled = false

[backup_encryption]
# Turn on encryption
enabled = true

cryptographic algorithm
algorithm = "aes-256-gcm"

# Key encapsulation method
key_wrap_algorithm = "x25519"

# Path to the public key file.The public key of the recipient (viewer of the backup) is stored here
public_key_file = "C:\\test_key\\ppk.pub"

# Delete clear text after encryption
delete_plain_after_encrypt = true

2. Generate key see –––––––––––––– Link pending

Perform the preliminary checks: §.

Perform application data or database backup pre-checks

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --config-home %USERPROFILE%\.peppykeep\conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : C:\tmp\prj_a
Location   : Local
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

or @

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : C:\tmp\prj_a
Location   : Local
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

⚠️ Note: The suffix name of the encrypted file is .ppke

Perform a backup

Perform application data or database backups

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --apply --config-home %USERPROFILE%\.peppykeep\conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --apply --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

[1/3] Prepare local workspace
[2/3] Copy application data
[3/3] Create and encrypt backup artifact
Encryption progress: started (160 B)
Encryption progress: 100% (160 B/160 B)
Encryption progress: 100% (160 B/160 B)
=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : C:\tmp\prj_a
Location     : Local
Force        : false
Artifact     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260716_184601.ppke
ArtifactSize : 324 B
Status       : Command completed successfully.

or @

[1/3] Prepare local workspace
[2/3] Export database
mysqldump output:

[3/3] Create and encrypt backup artifact
Encryption progress: started (1.2 KiB)
Encryption progress: 100% (1.2 KiB/1.2 KiB)
Encryption progress: 100% (1.2 KiB/1.2 KiB)
=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : Db
DataDir      : C:\tmp\prj_a
Location     : Local
Force        : false
Artifact     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260716_190508.ppke
ArtifactSize : 1.3 KiB
Status       : Command completed successfully.

⚠️ Note: The suffix name of the encrypted file is .ppke

Backup to remote

enforce_provisioning_action

1.bak.toml

bak_location_type = "local_and_remote"

[object_storage]
enabled = true

[backup_encryption]
# Turn on encryption
enabled = true

cryptographic algorithm
algorithm = "aes-256-gcm"

# Key encapsulation method
key_wrap_algorithm = "x25519"

# Path to the public key file.The public key of the recipient (viewer of the backup) is stored here
public_key_file = "C:\\test_key\\ppk.pub"

# Delete clear text after encryption
delete_plain_after_encrypt = true

2. Generate key see –––––––––––––– Link pending

Perform the preliminary checks: §.

Perform application data or database backup pre-checks

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --config-home %USERPROFILE%\.peppykeep\conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : C:\tmp\prj_a
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

or @

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : C:\tmp\prj_a
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

⚠️ Note: The suffix name of the encrypted file is .ppke

Execute Encryption

Perform application data or database backups

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --apply --config-home %USERPROFILE%\.peppykeep\conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --apply --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

[1/5] Prepare local workspace
[2/5] Copy application data
[3/5] Create and encrypt backup artifact
Encryption progress: started (161 B)
Encryption progress: 100% (161 B/161 B)
Encryption progress: 100% (161 B/161 B)
[4/5] Upload artifact to object storage
=== Upload Target ===
Provider  : s3
Bucket    : contentwork-dev
RemoteKey : test_717_file/test_717_file-bak_20260716_191434.ppke
Target    : s3://contentwork-dev/test_717_file/test_717_file-bak_20260716_191434.ppke
Upload progress: started single-part upload (325 B)
Upload progress: 100% (325 B/325 B)
=== Upload Completed ===
Provider  : s3
Bucket    : contentwork-dev
RemoteKey : test_717_file/test_717_file-bak_20260716_191434.ppke
Target    : s3://contentwork-dev/test_717_file/test_717_file-bak_20260716_191434.ppke
[5/5] Apply local retention policy
=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : C:\tmp\prj_a
Location     : LocalAndRemote
Force        : false
Artifact     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260716_191434.ppke
ArtifactSize : 325 B
Bucket       : contentwork-dev
RemoteKey    : test_717_file/test_717_file-bak_20260716_191434.ppke
Provider     : s3
Target       : s3://contentwork-dev/test_717_file/test_717_file-bak_20260716_191434.ppke
LocalCleanup : applied
Status       : Command completed successfully.

or @

[1/5] Prepare local workspace
[2/5] Export database
mysqldump output:

[3/5] Create and encrypt backup artifact
Encryption progress: started (1.2 KiB)
Encryption progress: 100% (1.2 KiB/1.2 KiB)
Encryption progress: 100% (1.2 KiB/1.2 KiB)
[4/5] Upload artifact to object storage
=== Upload Target ===
Provider  : s3
Bucket    : contentwork-dev
RemoteKey : test_717_file/test_717_file-bak_20260716_191440.ppke
Target    : s3://contentwork-dev/test_717_file/test_717_file-bak_20260716_191440.ppke
Upload progress: started single-part upload (1.3 KiB)
Upload progress: 100% (1.3 KiB/1.3 KiB)
=== Upload Completed ===
Provider  : s3
Bucket    : contentwork-dev
RemoteKey : test_717_file/test_717_file-bak_20260716_191440.ppke
Target    : s3://contentwork-dev/test_717_file/test_717_file-bak_20260716_191440.ppke
[5/5] Apply local retention policy
=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : Db
DataDir      : C:\tmp\prj_a
Location     : LocalAndRemote
Force        : false
Artifact     : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260716_191440.ppke
ArtifactSize : 1.3 KiB
Bucket       : contentwork-dev
RemoteKey    : test_717_file/test_717_file-bak_20260716_191440.ppke
Provider     : s3
Target       : s3://contentwork-dev/test_717_file/test_717_file-bak_20260716_191440.ppke
LocalCleanup : applied
Status       : Command completed successfully.

⚠️ Note: The suffix name of the encrypted file is .ppke

Normal Encrypted File (.ppke) Recovery

Configuration

bak.toml：

[restore_encryption]
private_key_file = "C:\\test_key\\ppk.key"

private_key_passphrase_env = "PPKPKPSW"

allow_prompt = true

PreCheckout

Perform application data or database backup pre-checks

ppk decrypt --input "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_093325.ppke" --extract --output-dir "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_mysql_102" --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action  : decrypt
Input   : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_093325.ppke
Output  : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_mysql_102
PrivKey : <configured restore_encryption.private_key_file>
Prompt  : false
Next    : Re-run with --apply to execute.

Recover

Perform application data or database backups

ppk decrypt --input "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_093325.ppke" --extract --output-dir "C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_mysql_102" --apply --config-home %USERPROFILE%\.peppykeep\conf

When the pre-test is successful, the output is as follows:

=== Completed ===
Action  : decrypt
Input   : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_717_file\test_717_file-bak_20260717_093325.ppke
Output  : C:\Users\admin\AppData\Local\Temp\backup\peppykeep\test_mysql_102
PrivKey : C:\test_key\ppk.key
Status  : Command completed successfully.

Order Details Reference

• View ppk decrypt command details

Generate Key

Enter password manually

Perform the preliminary checks: §.

ppk key generate --key-home C:\test_key --prompt-for-passphrase

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action    : key generate
OutputDir : C:\test_key
Overwrite : false
Prompt    : true
Next      : Re-run with --apply to execute.

Execute Build

ppk key generate --key-home C:\test_key --prompt-for-passphrase --apply

On success, the output is as follows:

Input passphrase for generated private key: [hidden]
=== Completed ===
Action      : key generate
PrivateKey  : C:\test_key\ppk.key
PublicKey   : C:\test_key\ppk.pub
PasswordFile: C:\test_key\ppk.pwd
Permissions : chmod 600 C:\test_key\ppk.key && chmod 644 C:\test_key\ppk.pub
Status      : Command completed successfully.

Read environment variable password

Perform the preliminary checks: §.

REMSet environment variable
set PPKPKPSW=123456
ppk key generate --key-home C:\test_key

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action    : key generate
OutputDir : C:\test_key
Overwrite : false
Prompt    : false
Next      : Re-run with --apply to execute.

Execute Build

ppk key generate --key-home C:\test_key --apply

On success, the output is as follows:

=== Completed ===
Action      : key generate
PrivateKey  : C:\test_key\ppk.key
PublicKey   : C:\test_key\ppk.pub
PasswordFile: C:\test_key\ppk.pwd
Permissions : chmod 600 C:\test_key\ppk.key && chmod 644 C:\test_key\ppk.pub
Status      : Command completed successfully.

Order Details Reference

• key generate

Disaster Preparedness Drill

Regularly verify that backup, decryption, and recovery links are still available.

场景化步骤见 定期做恢复验证。Windows 上可配合 bak.toml 中的 [drill] / [drill.mysql] 使用，详见 bak.toml 配置说明。

Quick Examples

Download the remote encrypted backup and decrypt (the path is replaced by the actual environment):

peppykeep backup download-artifact --apply --remote-key project-a/backup.ppke --output-file %TEMP%\backup.ppke --config-home %USERPROFILE%\.peppykeep\conf

ppk decrypt --input %TEMP%\backup.ppke --output %TEMP%\backup.ppk --apply --config-home %USERPROFILE%\.peppykeep\conf

The commands and parameters of the MySQL Disaster Preparedness Drill are shown in the command reference (to be added to the standalone command page, you can link here).

Back to Encryption & Recovery Feature Index

Notification

This section is used to explain the configuration and use of message capabilities such as backup task alarms and webhook notifications on Windows.

The current document is to be added after alignment with the product MRD. Relevant configuration portals:

• app.toml notification configuration
• Backup Task Status and Alarms

Returns the Windows function block index

Universal Sense Backup

Generic App Backup: A common application-aware path for common workloads such as MySQL; requires a valid encrypted backup, and this document is an additional capability purchased separately. Operating documents for Windows platform to be added. See Official Website Pricing for instructions.

Returns the Windows function block index

Dedicated Aware Backup

Dedicated App Backup: Dedicated application-aware backup for customer-specific workloads, with sales assistance for onboarding and deployment.

Standard Windows operating manuals do not apply to such customized scenarios. For evaluation, contact Contact support.

Subscription instructions are available at Official Website Pricing.

Returns the Windows function block index

macOS and Linux Download and Installation

Go to the PeppyKeep official website download page to download and install

This manual does not repeat the maintenance and installation steps. Once the installation is complete, read the macOS and Linux command line feature guide to configure and perform the first backup. Linux supports only the command line, but can be invoked or managed by the Windows or macOS desktop.

macOS and Linux Command Line Features Guide

This page and its function blocks are for command line use on macOS and Linux. Both systems use the same PeppyKeep commands, parameters, and default configuration directory; only the installation environment and a few system path differences are noted.

The desktop is under development, and the plan is to support Windows and macOS only, not Linux. Linux hosts are available only from the command line, but can be invoked or managed from the Windows or macOS desktop.

Configure Folders

After install, ~/.peppykeep/conf gets app.toml, bak.toml, and prj.toml. Before the first backup, confirm they exist and match your environment (MySQL, paths, object storage). Bulk MySQL jobs also need mysql_bak_request.toml.

Field reference: Configuration files (app.toml, bak.toml, prj.toml, etc.). Use --config-home or env var PPK for the config directory.

Quick Start (Basic Application Data Backup)

# 1. Confirm that the download and installation have been completed on the official website

# 2. Confirm that app.toml, bak.toml, prj.toml already exist under ~/.peppykeep/conf, and modify by environment (such as data_dir of prj.toml)

# 3. Prepare Test Data
mkdir -p /tmp/test_file_717 && echo "sample" > /tmp/test_file_717/sample.txt

# 4. Pre-inspection
peppykeep backup run --config-home ~/.peppykeep/conf --bak-type app-data

# 5. Formal backup (local + upload, configured by bak.toml)
peppykeep backup run --apply --config-home ~/.peppykeep/conf --bak-type app-data

’–no-upload` can only be added when backing up locally.

Download & Install

Go to the PeppyKeep official website download page to download and install

Function elements

Follow the scenario step by step, each section contains configuration points, dry-run and formal execution (--apply):

Function block index

Configuration Specification (CS)

The following files are automatically generated in the default configuration directory during installation. Please confirm that the files exist before modifying them:

• app.toml
• bak.toml
• prj.toml

First Backup

Please complete the download and installation on the PeppyKeep official website download page first. This page only describes the first backup after the installation is complete.

1. Verify that the auto-generated app.toml, bak.toml, prj.toml are installed under the default configuration directory ~/.peppykeep/conf and modify the necessary fields according to the actual environment
2. Prepare test data (optional):

mkdir -p /tmp/test_file_717
echo "sample content" > /tmp/test_file_717/sample.txt

3. Pre-test (dry-run, no backup file):

peppykeep backup run --config-home ~/.peppykeep/conf

4. After confirming that the output is correct, formally execute:

peppykeep backup run --apply --config-home ~/.peppykeep/conf

Examples of pre-check output (reference configuration ~/.peppykeep/conf):

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : /tmp/test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

Only dry-run without `--apply’. The first execution may trigger Device Bind Login, please complete authorization before timeout.

macOS function blocks

The following sections demonstrate using the reference configuration ~/.peppykeep/conf to complete common operations on macOS. Each section is recommended to be formally executed by first dry-run followed by --apply.

Function blocks are organized hierarchically by Official Website Pricing.

Accounts & General

Shared across plans, not sold separately.

Основні функції

Encryption and recovery features

Universal Sense Backup

Dedicated Aware Backup

Accounts & General

The features in this section are not sold separately with the subscription plan and are available to all macOS users.

Returns the macOS function block index

Theme My Login Action

When the backup/restore command is executed for the first time, if the device is not already bound locally, the CLI pauses and prompts to complete the authorization in the browser. You can also take the initiative to execute the login command.

View Version

peppykeep --version

Example output:

peppykeep 26.7.836+20260716152959

Login (using cached credentials)

peppykeep login --config-home ~/.peppykeep/conf

When logged in and the credentials are valid:

Action = auth login
Status = SUCCESS
AuthState = CACHED

Refresh Login/Device Bindings

When you need to rebind or refresh the authorization:

peppykeep login --refresh --config-home ~/.peppykeep/conf

Example output:

Action = auth login
Status = REQUIRED
OpenUrl = https://www.peppykeep.com/console/device/binding?auth_session_id=...
ManualCodeUrl = https://www.peppykeep.com/console/device/code/
DeviceCode = XXXX-XXXX-XXXX-XXXX

Follow these steps to bind this device:

1. Open this link in your desktop browser
   https://www.peppykeep.com/console/device/code/

   Or open official site:
   Login -> Console -> Devices -> Bind a new device

2. Enter this device code
   XXXX-XXXX-XXXX-XXXX

Waiting for device authorization...
Status = AUTHORIZED

Action = auth login
Status = SUCCESS
AuthState = LOGGED_IN
CachePath = /path/to/user/.peppykeep/auth/license_bundle.enc

Once the binding is complete, the interrupted backup/restore command will continue to execute automatically. Do not share DeviceCode with others.

Backup pre-test function

Only dry-run ⚠️ without --apply, no backup file will be written. The first execution may trigger the device binding login, please complete the authorization before the timeout.

Pre-check command

peppykeep backup run --config-home ~/.peppykeep/conf

Sample Normal Output

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : /tmp/test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

Order Details Reference

• Click for command details

Основні функції

The basic data backup includes unencrypted backups, universal MySQL application-aware unencrypted backups, basic recovery, execution history and version browsing, etc.; see the following function page for object storage upload download and retention policy cleaning.

Returns the macOS function block index

Basic Application Data Backup

Taking the reference configuration directory ~/.peppykeep/conf as an example, this article demonstrates the backup application directory file on macOS. It is recommended to dry-run (without --apply) every step before formally executing.

Prepare test data

mkdir -p /tmp/test_file_717
echo "sample content" > /tmp/test_file_717/sample.txt

Backup to local

enforce_provisioning_action

1. app.toml — 详见 app.toml 配置说明

2. bak.toml — Key Fragments (local, non-encrypted examples only):

[public]
bak_type = "app_data"
bak_location_type = "local"
history_bak_num = 3
log_level = "INFO"
log_dir = "/tmp/logs/peppykeep"
local_bak_home = "/tmp/backup/peppykeep"
local_tmp_home = "/tmp/.peppykeep_tmp"
max_bak_queue_size = 1

[backup_encryption]
enabled = false

完整参数见 bak.toml 配置说明。

3. prj.toml — Key Fragments:

[local]
prj_key = "test_717_file"
data_dir = "/tmp/test_file_717"

详见 prj.toml 配置说明。

Perform the preliminary checks: §.

peppykeep backup run \
  --config-home ~/.peppykeep/conf \
  --bak-type app-data

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : /tmp/test_file_717
Location   : Local
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Perform a backup

peppykeep backup run \
  --config-home ~/.peppykeep/conf \
  --apply \
  --bak-type app-data

Example output on success:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : /tmp/test_file_717
Location     : Local
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260730_114551.ppk
ArtifactSize : 291 B
Status       : Command completed successfully.

Product extension: unencrypted as.ppk; .ppke 'when [backup_encryption] enabled = true `is enabled.

Backup to local and upload object store

When bak_location_type = "local_and_remote" and [object_storage] enabled = true in ’bak.toml`, the object storage is automatically uploaded after the backup is completed.

enforce_provisioning_action

bak.toml Key Fragments (S3 compatible storage example):

[public]
bak_type = "app_data"
bak_location_type = "local_and_remote"
history_bak_num = 3
log_level = "INFO"
log_dir = "/tmp/logs/peppykeep"
local_bak_home = "/tmp/backup/peppykeep/test_717_file"
local_tmp_home = "/tmp/.peppykeep_tmp"
max_bak_queue_size = 1

[object_storage]
enabled = true
provider = "s3"
bucket = "VoosTestBucket"
prefix = ""
endpoint = "https://s3.ca-east-006.backblazeb2.com"
region = "ca-east-006"
access_key_id = "<YOUR_ACCESS_KEY_ID>"
access_key_secret = "<YOUR_ACCESS_KEY_SECRET>"
path_style = true

[backup_encryption]
enabled = true
algorithm = "aes-256-gcm"
key_wrap_algorithm = "x25519"
public_key_file = "/tmp/ppk_key/ppk.pub"
delete_plain_after_encrypt = true

Perform the preliminary checks: §.

peppykeep backup run \
  --config-home ~/.peppykeep/conf \
  --bak-type app-data

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : /tmp/test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

Perform a backup

peppykeep backup run \
  --config-home ~/.peppykeep/conf \
  --apply \
  --bak-type app-data

Example output on success:

[1/5] Prepare local workspace
[2/5] Copy application data
[3/5] Create and encrypt backup artifact
Encryption progress: started (292 B)
Encryption progress: 100% (292 B/292 B)
[4/5] Upload artifact to object storage
=== Upload Target ===
Provider  : s3
Bucket    : VoosTestBucket
RemoteKey : test_717_file/test_717_file-bak_20260730_114555.ppke
Target    : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260730_114555.ppke
Upload progress: 100% (456 B/456 B)
[5/5] Apply local retention policy
=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : /tmp/test_file_717
Location     : LocalAndRemote
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file/test_717_file-bak_20260730_114555.ppke
ArtifactSize : 456 B
Bucket       : VoosTestBucket
RemoteKey    : test_717_file/test_717_file-bak_20260730_114555.ppke
Provider     : s3
Target       : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260730_114555.ppke
LocalCleanup : applied
Status       : Command completed successfully.

Local Only, No Upload (Temporary Override)

When configured to local_and_remote but only want to keep local this time:

peppykeep backup run \
  --config-home ~/.peppykeep/conf \
  --apply \
  --bak-type app-data \
  --no-upload

Order Details Reference

• backup run command description

Database backup

Backup to local

enforce_provisioning_action

1. app.toml

# Log storage directory/tmp (allow to be followed by any subdirectory)
dir = "/tmp/log/peppykeep"

# Log file name (full path:/tmp/log/peppykeep/app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml

# Backup type: database
bak_type = "db"

# Backups are also saved locally
bak_location_type = "local"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log storage directory/tmp (allow to be followed by any subdirectory)
log_dir = "/tmp/logs/peppykeep"

# Local backup storage home directory/tmp (allow to be followed by any subdirectory)
local_bak_home = "/tmp/backup/peppykeep"

# Local Temporary Working Directory/tmp (allows any subdirectory to follow)
local_tmp_home = "/tmp/.peppykeep_tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

[mysql]
mysql_ip = "localhost"
mysql_port = 3306
mysql_user_name = "root"
mysql_pwd = "root"
# mysqldump tool path
mysqldump_path = "/usr/local/bin/mysqldump"
skip_ssl = true
# docker_container_name = "non-exists-name" # When commenting on this line (None), the local mysqldump command is used, otherwise the docker exec command will be executed
# Docker Command Path (for containerized backups)
docker_cmd_path = "/usr/bin/docker"

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "/tmp/test_file_717"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# Database Backup Precheck
peppykeep backup run --bak-type db --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

admindeMac-mini-2:ldpt admin$ peppykeep backup run --bak-type db
=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : /tmp/test_file_717
Location   : Local
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Performing a Database Backup

peppykeep backup run --apply --bak-type db --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action   : backup run
Project  : test_717_file
BakType  : Db
DataDir  : /tmp/test_file_717
Location : Local
Force    : false
Artifact : /tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260703_171840.ppk
Status   : Command completed successfully.

Result

Backup to Object Storage

enforce_provisioning_action

1. app.toml

# Log storage directory/tmp (allow to be followed by any subdirectory)
dir = "/tmp/log/peppykeep"

# Log file name (full path:/tmp/log/peppykeep/app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml (S3 as an example)

# Backup type: database
bak_type = "db"

# Backups are also saved locally
bak_location_type = "local_and_remote"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log storage directory/tmp (allow to be followed by any subdirectory)
log_dir = "/tmp/my_test_peppykeep/logs"

# Local backup storage home directory/tmp (allow to be followed by any subdirectory)
local_bak_home = "/tmp/my_test_peppykeep/backup"

# Local Temporary Working Directory/tmp (allows any subdirectory to follow)
local_tmp_home = "/tmp/my_test_peppykeep/.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

[mysql]
Database Host
mysql_ip = "192.0.2.10"
Database Port
mysql_port = 3306
Databse username
mysql_user_name = "remote_user"
Database Pass
mysql_pwd = "root"
# mysqldump tool path
mysqldump_path = "/opt/homebrew/bin/mysqldump"
# Docker Command Path (for containerized backups)
docker_cmd_path = "/usr/local/bin/docker"

# Enable Object Storage
[object_storage]
enabled = true

# Using S3 protocol (Backblaze B2 compatible)
provider = "s3"

# Bucket Name
bucket = "TestBucket"

# Object key prefix (like folder path)
prefix = "test_local"

# S3 Compatible Endpoints (Backblaze B2 + East)
endpoint = "https://s3.xxxxxxxxxxxxxx.com"

Region
region = "ca-east-006"

Access Key ID
access_key_id = "xxxxxxxxxxxxxx"

Access key
access_key_secret = "xxxxxxxxxxxxxx"

# Use path style URL (bucket/object instead of web hosting style)
path_style = true

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "/tmp/test_data"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# Database Backup Precheck
peppykeep backup run --bak-type db --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : /tmp/test_file_717
Location   : LocalAndRemote
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Performing a Database Backup

peppykeep backup run --apply --bak-type db --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : Db
DataDir      : /tmp/test_file_717
Location     : LocalAndRemote
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260703_172943.ppk
Bucket       : VoosTestBucket
RemoteKey    : test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk
Provider     : s3
Target       : s3://VoosTestBucket/test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk
LocalCleanup : applied
Status       : Command completed successfully.

Result

Order Details Reference

• Click for command details

Docker Backup

Backup to local

enforce_provisioning_action

1. app.toml

# Log storage directory/tmp (allow to be followed by any subdirectory)
dir = "/tmp/log/peppykeep"

# Log file name (full path:/tmp/log/peppykeep/app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml

# Backup type is docker backup
bak_type = "db_and_app_data"

# Backups are also saved locally
bak_location_type = "local"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log storage directory/tmp (allow to be followed by any subdirectory)
log_dir = "/tmp/logs/peppykeep"

# Local backup storage home directory/tmp (allow to be followed by any subdirectory)
local_bak_home = "/tmp/backup/peppykeep"

# Local Temporary Working Directory/tmp (allows any subdirectory to follow)
local_tmp_home = "/tmp/.peppykeep_tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "root"
mysql_pwd = "root"
# mysqldump tool path
mysqldump_path = "/usr/bin/mysqldump"
skip_ssl = true
docker_container_name = "ppk-mysql-test"
# Docker Command Path (for containerized backups)
docker_cmd_path = "/usr/bin/docker"

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "/tmp/test_file_717"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# docker Backup Precheck (Database + App Catalog)
peppykeep backup run --bak-type db-and-app-data --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : DbAndAppData
DataDir    : /tmp/test_file_717
Location   : Local
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Perform a docker backup

peppykeep backup run --bak-type db-and-app-data --apply --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : DbAndAppData
DataDir      : /tmp/test_file_717
Location     : Local
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file/test_717_file-bak_20260729_173824.ppke
ArtifactSize : 1.5 KiB
Status       : Command completed successfully.

Result

Backup to Object Storage

enforce_provisioning_action

1. app.toml

# Log storage directory/tmp (allow to be followed by any subdirectory)
dir = "/tmp/log/peppykeep"

# Log file name (full path:/tmp/log/peppykeep/app.log)
file_name = "app.log"

# Level: error, warn, info, debug, trace Log level is debug (output all debug information)
level = "debug"

点击查看详情

2. bak.toml (S3 as an example)

# Backup Type: Database + App Catalog (Docker Scenario)
bak_type = "db_and_app_data"

# Save backups both locally and remotely
bak_location_type = "local_and_remote"

# Keep last n historical backups locally
history_bak_num = n

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log storage directory/tmp (allow to be followed by any subdirectory)
log_dir = "/tmp/my_test_peppykeep/logs"

# Local backup storage home directory/tmp (allow to be followed by any subdirectory)
local_bak_home = "/tmp/my_test_peppykeep/backup"

# Local Temporary Working Directory/tmp (allows any subdirectory to follow)
local_tmp_home = "/tmp/my_test_peppykeep/.tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

[mysql]
# docker host
mysql_ip = "192.0.2.10"
# docker port
mysql_port = 3306
# dockerusername
mysql_user_name = "remote_user"
# docker Password
mysql_pwd = "root"
# mysqldump tool path
mysqldump_path = "/usr/bin/mysqldump"
docker_container_name = "ppk-mysql-test"
# Docker Command Path (for containerized backups)
docker_cmd_path = "/usr/local/bin/docker"

# Enable Object Storage
[object_storage]
enabled = true

# Using S3 protocol (Backblaze B2 compatible)
provider = "s3"

# Bucket Name
bucket = "TestBucket"

# Object key prefix (like folder path)
prefix = "test_local"

# S3 Compatible Endpoints (Backblaze B2 + East)
endpoint = "https://s3.xxxxxxxxxxxxxx.com"

Region
region = "ca-east-006"

Access Key ID
access_key_id = "xxxxxxxxxxxxxx"

Access key
access_key_secret = "xxxxxxxxxxxxxx"

# Use path style URL (bucket/object instead of web hosting style)
path_style = true

# Backup Encryption Configuration
[backup_encryption]
# Turn off encryption
enabled = false

点击查看详情

3. prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local data storage directory (temporary path, configurable)
data_dir = "/tmp/test_data"

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# docker Backup Precheck (Database + App Catalog)
peppykeep backup run --bak-type db-and-app-data --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : DbAndAppData
DataDir    : /tmp/test_data
Location   : LocalAndRemote
Encryption : false
Force      : false
Next       : Re-run with --apply to execute.

Result

Perform a backup

Perform a docker backup

peppykeep backup run --bak-type db-and-app-data --apply --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : DbAndAppData
DataDir      : /tmp/test_file_717
Location     : LocalAndRemote
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file/test_717_file-bak_20260729_174638.ppke
ArtifactSize : 1.5 KiB
Bucket       : VoosTestBucket
RemoteKey    : test_717_file/test_717_file-bak_20260729_174638.ppke
Provider     : s3
Target       : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260729_174638.ppke
LocalCleanup : applied
Status       : Command completed successfully.

Result

Batch Backup Database

Multiple libraries need to be backed up at once under the same MySQL instance, and the filtering rules of each library table may be different. Use mysql_bak_request.toml with backup mysql-db-list.

Backup to local

enforce_provisioning_action

1. bak.toml — need to include MySQL connection and local path (bak_type has no effect on mysql-db-list but [mysql] is required):

[public]
bak_location_type = "local"
history_bak_num = 3
log_level = "DEBUG"
log_dir = "/tmp/logs/peppykeep"
local_bak_home = "/tmp/backup/peppykeep"
local_tmp_home = "/tmp/.peppykeep_tmp"
max_bak_queue_size = 1

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "root"
mysql_pwd = "root"
mysqldump_path = "/usr/local/bin/mysqldump"
skip_ssl = true

完整参数见 bak.toml 配置说明。

2. mysql_bak_request.toml

instance_name = "test_717_file11111"
upload_to_oss = false
remove_older_files = true
remove_older_oss_files = false   # Must be false when upload_to_oss is false

[base]
uuid = ""
name = "batch-mysql-task"
desc = "backup multiple databases"

[[db_config_list]]
db_name = "7.12database1"
include_table_list = []
exclude_table_list = []

[[db_config_list]]
db_name = "7.12database2"
include_table_list = []
exclude_table_list = []

See mysql_bak_request.toml for details.

Perform the preliminary checks: §.

peppykeep backup mysql-db-list \
  --request-file ~/.peppykeep/conf/mysql_bak_request.toml \
  --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action        : backup mysql-db-list
RequestFile   : /path/to/user/.peppykeep/conf/mysql_bak_request.toml
Instance      : test_717_file11111
DbCount       : 2
Upload        : false
LocalCleanup  : true
RemoteCleanup : false
Docker        : <none>
Next          : Re-run with --apply to execute.

Perform a backup

peppykeep backup mysql-db-list \
  --request-file ~/.peppykeep/conf/mysql_bak_request.toml \
  --apply \
  --config-home ~/.peppykeep/conf

Example output on success:

=== Completed ===
Action        : backup mysql-db-list
RequestFile   : /path/to/user/.peppykeep/conf/mysql_bak_request.toml
Instance      : test_717_file11111
DbCount       : 2
Upload        : false
LocalCleanup  : true
RemoteCleanup : false
Docker        : <none>
Status        : Command completed successfully.

Backup to Object Storage

在 mysql_bak_request.toml 中设置 upload_to_oss = true，并在 bak.toml 配置 [object_storage]。上传与保留策略见 备份文件上传对象存储 与 bak.toml 说明。

Order Details Reference

• backup mysql-db-list

Remote backup download

Download an existing backup file from the object store to your local

enforce_provisioning_action

1. bak.toml (S3 as an example)

# Enable Object Storage
[object_storage]
enabled = true

# Using S3 protocol (Backblaze B2 compatible)
provider = "s3"

# Bucket Name
bucket = "TestBucket"

# Object key prefix (like folder path)
prefix = "test_local"

# S3 Compatible Endpoints (Backblaze B2 + East)
endpoint = "https://s3.xxxxxxxxxxxxxx.com"

Region
region = "ca-east-006"

Access Key ID
access_key_id = "xxxxxxxxxxxxxx"

Access key
access_key_secret = "xxxxxxxxxxxxxx"

# Use path style URL (bucket/object instead of web hosting style)
path_style = true

点击查看详情

Perform the preliminary checks: §.

Open Terminal Execution

# Database Backup Precheck
peppykeep backup download-artifact --remote-key test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk --output-file /tmp/test/testdb.ppk --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action         : backup download-artifact
RemoteKey      : test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk
Output         : /tmp/test/testdb.ppk
Bucket         : VoosTestBucket
Provider       : s3
RestoreArchive : false
Wait           : false
RestoreDays    : 1
WaitTimeout    : 1800
PollInterval   : 30
Next           : Re-run with --apply to execute.

Result

Perform a backup

Performing a Database Backup

peppykeep backup download-artifact --remote-key test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk --output-file /tmp/test/testdb.ppk --apply --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action         : backup download-artifact
RemoteKey      : test_local_voos/test_717_file/test_717_file-bak_20260703_172943.ppk
Output         : /tmp/test/testdb.ppk
Bucket         : VoosTestBucket
Provider       : s3
RestoreArchive : false
Resumed        : false
Written        : 0
TotalSize      : 1186
Status         : Command completed successfully.

Result

Order Details Reference

• Click for command details

Backup File Upload Object Storage

enforce_provisioning_action

[object_storage]
enabled = true

provider = "s3"

bucket = "VoosTestBucket"

prefix = ""

endpoint = "https://s3.ca-east-006.backblazeb2.com"

region = "ca-east-006"

access_key_id = "<YOUR_ACCESS_KEY_ID>"

access_key_secret = "<YOUR_ACCESS_KEY_SECRET>"

path_style = true

Perform the preliminary checks: §.

peppykeep backup upload-artifact --input-file /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action    : backup upload-artifact
Input     : /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke
Bucket    : VoosTestBucket
RemoteKey : test_717_file/test_717_file-bak_20260717_142437.ppke
Provider  : s3
Target    : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260717_142437.ppke
Next      : Re-run with --apply to execute.

Performing an upload

peppykeep backup upload-artifact --input-file /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke --apply --config-home ~/.peppykeep/conf

On success, the output is as follows:

=== Completed ===
Action    : backup upload-artifact
Input     : /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke
Bucket    : VoosTestBucket
RemoteKey : test_717_file/test_717_file-bak_20260717_142437.ppke
Provider  : s3
Target    : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260717_142437.ppke
Status    : Command completed successfully.

Order Details Reference

• Click for command details

Delete local old backup files

enforce_provisioning_action

1.prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_717_file"
# Local Data Storage Directory
data_dir = "/path/to/user/work/test_data"

2.bak.toml

[public]
# Keep last 3 historical backups locally
history_bak_num = 1

# Log Storage Directory
log_dir = "/tmp/logs/peppykeep"

# Local Backup Storage Home Directory
local_bak_home = "/tmp/backup/peppykeep"

# Local Temporary Working Directory
local_tmp_home = "/tmp/.peppykeep_tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

Perform the preliminary checks: §.

Open Terminal Execution

peppykeep cleanup local --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action  : cleanup local
Project : test_717_file
Force   : false
Next    : Re-run with --apply to execute.

Result

Delete execution

Delete local old backups

peppykeep cleanup local --apply --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action  : cleanup local
Project : test_717_file
Force   : false
Status  : Command completed successfully.
2026-07-14T07:21:52.415444Z DEBUG peppykeep: src/main.rs:1873: Finished.

Result

Order Details Reference

• Click for command details

Delete remote old backup files

Purge historical backups in the object store according to the [remote.retain] policy in ‘prj.toml’. For the first time, it is recommended to keep really_remove = false for analysis only, and then change it to true after confirmation.

enforce_provisioning_action

参考 bak.toml 中的 [object_storage] 与 prj.toml 中的 [remote.retain]。

Perform the preliminary checks: §.

peppykeep cleanup object-storage --config-home ~/.peppykeep/conf

Example output:

=== Dry Run ===
Action  : cleanup object-storage
Project : test_717_file
Force   : false
Next    : Re-run with --apply to execute.

Delete execution

peppykeep cleanup object-storage --force --apply --config-home ~/.peppykeep/conf

Example of successful output:

=== Completed ===
Action  : cleanup object-storage
Project : test_717_file
Force   : true
Status  : Command completed successfully.

Order Details Reference

• Click for command details

mysql database recovery

enforce_provisioning_action

Perform the preliminary checks: §.

admindeMac-mini-2:~ admin$ peppykeep restore mysql --backup-file /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_121459.ppke  --target-db-name remote_user

=== Dry Run ===
Action            : restore mysql
Project           : test_717_file
SourceDb          : ldbak_test
InputSource       : local_file
BackupFile        : /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_121459.ppke
TargetDb          : remote_user
Workspace         : /tmp/ppk-restore-mysql/test_717_file/20260717_140955
ExecutionMode     : native
ContainerRuntime  : <none>
ContainerName     : <none>
MysqlHost         : 192.0.2.10
MysqlPort         : 3306
MysqlClient       : /opt/homebrew/bin/mysql
DropTargetDb      : false
ConfirmTargetDb   : <none>
DecryptPrivateKey : <configured restore_encryption.private_key_file>
PromptPassphrase  : false
CheckSqlFile      : <none>
CleanWorkspace    : false
KeepWorkspace     : true
Next              : Re-run with --apply to execute.

Perform a restore.

Perform application data or database backups

peppykeep restore mysql --backup-file /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_121459.ppke  --target-db-name remote_user --apply --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Completed ===
Action           : restore mysql
Project          : test_717_file
SourceDb         : ldbak_test
InputSource      : local_file
TargetDb         : remote_user
BackupFile       : /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_121459.ppke
Archive          : /tmp/ppk-restore-mysql/test_717_file/20260717_140949/test_717_file-bak_20260717_121459.ppk
SqlFile          : /tmp/ppk-restore-mysql/test_717_file/20260717_140949/extracted/ppk_data/sql/test_717_file_export.sql
Workspace        : /tmp/ppk-restore-mysql/test_717_file/20260717_140949
WorkspaceRemoved : false
Status           : Command completed successfully.

Order Details Reference

• View ppk decrypt command details

Encryption and recovery features

Provide encrypted backup and recovery, oversized directory volume, disaster recovery drill and other capabilities.

Returns the macOS function block index

Extra Large Directory Volume Archive Backup

The extra large directory usesbackup large-dir, which is independent ofbak_typein bak.toml '; you need to configure local_tmp_home , optional [object_storage] , and specify data_dir in prj.toml `.

Backup to local

enforce_provisioning_action

1.prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_mysql_102"
# Local Data Storage Directory
data_dir = "/path/to/user/work/test_data"

2.bak.toml

[public]

# Backups are also saved locally
bak_location_type = "local"

# Keep last 3 historical backups locally
history_bak_num = 3

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log Storage Directory
log_dir = "/tmp/logs/peppykeep"

# Local Backup Storage Home Directory
local_bak_home = "/tmp/backup/peppykeep"

# Local Temporary Working Directory
local_tmp_home = "/tmp/.peppykeep_tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

Perform the preliminary checks: §.

Open Terminal Execution

# Oversized Directory Volume Archive Backup Precheck
peppykeep backup large-dir run --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action      : backup large-dir run
Project     : test_mysql_102
DataDir     : /path/to/user/work/test_data
ChunkSize   : 4.0 GiB
Compression : none
Upload      : false
Resume      : false
TaskRoot    : /tmp/.peppykeep_tmp/tasks
Next        : Re-run with --apply to execute.

Result

Perform a backup

Performing Extra Large Directory Volume Archive Backups

peppykeep backup large-dir run --apply --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

Action           : backup large-dir run
TaskId           : 1784003117490
TaskDir          : /tmp/.peppykeep_tmp/tasks/test_mysql_102-1784003117490
Manifest         : /tmp/.peppykeep_tmp/tasks/test_mysql_102-1784003117490/manifest.json
State            : /tmp/.peppykeep_tmp/tasks/test_mysql_102-1784003117490/state.json
FileCount        : 4
TotalSize        : 64 B
Parts            : 1
ChunkSize        : 4.0 GiB
Compression      : none
Upload           : false
ManifestUploaded : false
Status           : Command completed successfully.

Result

Backup to Object Storage

enforce_provisioning_action

1.prj.toml

# Project identifiers for relative path and directory identification
prj_key = "test_mysql_102"
# Local Data Storage Directory
data_dir = "/path/to/user/work/test_data"

2.bak.toml

[public]

# Save backups both locally and remotely
bak_location_type = "local_and_remote"

# Keep last 3 historical backups locally
history_bak_num = 3

# Log level is debug mode (outputs the most detailed logs)
log_level = "DEBUG"

# Log Storage Directory
log_dir = "/tmp/logs/peppykeep"

# Local Backup Storage Home Directory
local_bak_home = "/tmp/backup/peppykeep"

# Local Temporary Working Directory
local_tmp_home = "/tmp/.peppykeep_tmp"

# The maximum length of the backup queue is 1 (serial execution, no concurrency)
max_bak_queue_size = 1

[object_storage]
# Enable Object Storage
enabled = true

# Using S3 protocol (Backblaze B2 compatible)
provider = "s3"

# Bucket Name
bucket = "VoosTestBucket"

# Object key prefix (like folder path)
prefix = "test_local_voos"

# S3 Compatible Endpoints (Backblaze B2 + East)
endpoint = "https://s3.ca-east-006.backblazeb2.com"

Region
region = "ca-east-006"

Access Key ID
access_key_id = "<YOUR_ACCESS_KEY_ID>"

Access key
access_key_secret = "<YOUR_ACCESS_KEY_SECRET>"

# Use path style URL (bucket/object instead of web hosting style)
path_style = true

Perform the preliminary checks: §.

Open Terminal Execution

admindeMac-mini-2:prj_a admin$ peppykeep backup large-dir run

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action      : backup large-dir run
Project     : test_mysql_102
DataDir     : /path/to/user/work/test_data
ChunkSize   : 4.0 GiB
Compression : none
Upload      : true
Resume      : false
TaskRoot    : /tmp/.peppykeep_tmp/tasks
Next        : Re-run with --apply to execute.

Result

Perform a backup

Performing Extra Large Directory Volume Archive Backups

peppykeep backup large-dir run --apply --config-home ~/.peppykeep/conf

After executing the backup command, the output on success is as follows:

=== Completed ===
Action           : backup large-dir run
TaskId           : 1784003365822
TaskDir          : /tmp/.peppykeep_tmp/tasks/test_mysql_102-1784003365822
Manifest         : /tmp/.peppykeep_tmp/tasks/test_mysql_102-1784003365822/manifest.json
State            : /tmp/.peppykeep_tmp/tasks/test_mysql_102-1784003365822/state.json
FileCount        : 4
TotalSize        : 64 B
Parts            : 1
ChunkSize        : 4.0 GiB
Compression      : none
Upload           : true
ManifestUploaded : true
Status           : Command completed successfully.

Result description (S3 as an example)

Order Details Reference

• Click for command details

Basic application and database general encryption backup

Backup to local

enforce_provisioning_action

1.bak.toml

bak_location_type = "local"

[object_storage]
enabled = false

[backup_encryption]
# Turn on encryption
enabled = true

cryptographic algorithm
algorithm = "aes-256-gcm"

# Key encapsulation method
key_wrap_algorithm = "x25519"

# Path to the public key file.The public key of the recipient (viewer of the backup) is stored here
public_key_file = "/tmp/key/ppk.pub"

# Delete clear text after encryption
delete_plain_after_encrypt = true

2. Generate key see –––––––––––––– Link pending

Perform the preliminary checks: §.

Perform application data or database backup pre-checks

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --config-home ~/.peppykeep/conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : /tmp/test_file_717
Location   : Local
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

or @

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : /tmp/test_file_717
Location   : Local
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

⚠️ Note: The suffix name of the encrypted file is .ppke

Perform a backup

Perform application data or database backups

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --apply --config-home ~/.peppykeep/conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --apply --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : /tmp/test_file_717
Location     : Local
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142418.ppke
ArtifactSize : 480 B
Status       : Command completed successfully.

or @

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : Db
DataDir      : /tmp/test_file_717
Location     : Local
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke
ArtifactSize : 1.3 KiB
Status       : Command completed successfully.

⚠️ Note: The suffix name of the encrypted file is .ppke

Backup to remote

enforce_provisioning_action

1.bak.toml

bak_location_type = "local_and_remote"

[object_storage]
enabled = true

[backup_encryption]
# Turn on encryption
enabled = true

cryptographic algorithm
algorithm = "aes-256-gcm"

# Key encapsulation method
key_wrap_algorithm = "x25519"

# Path to the public key file.The public key of the recipient (viewer of the backup) is stored here
public_key_file = "/tmp/key/ppk.pub"

# Delete clear text after encryption
delete_plain_after_encrypt = true

2. Generate key see –––––––––––––– Link pending

Perform the preliminary checks: §.

Perform application data or database backup pre-checks

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --config-home ~/.peppykeep/conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : AppData
DataDir    : /tmp/test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

or @

=== Dry Run ===
Action     : backup run
Project    : test_717_file
BakType    : Db
DataDir    : /tmp/test_file_717
Location   : LocalAndRemote
Encryption : true
Force      : false
Next       : Re-run with --apply to execute.

⚠️ Note: The suffix name of the encrypted file is .ppke

Perform a backup

Perform application data or database backups

# Performing an App Data Backup
peppykeep backup run --bak-type app-data --apply --config-home ~/.peppykeep/conf
or @
# Performing a Database Backup
peppykeep backup run --bak-type db --apply --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : AppData
DataDir      : /tmp/test_file_717
Location     : LocalAndRemote
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142723.ppke
ArtifactSize : 481 B
Bucket       : VoosTestBucket
RemoteKey    : test_717_file/test_717_file-bak_20260717_142723.ppke
Provider     : s3
Target       : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260717_142723.ppke
LocalCleanup : applied
Status       : Command completed successfully.

or @

=== Completed ===
Action       : backup run
Project      : test_717_file
BakType      : Db
DataDir      : /tmp/test_file_717
Location     : LocalAndRemote
Force        : false
Artifact     : /tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142749.ppke
ArtifactSize : 1.3 KiB
Bucket       : VoosTestBucket
RemoteKey    : test_717_file/test_717_file-bak_20260717_142749.ppke
Provider     : s3
Target       : s3://VoosTestBucket/test_717_file/test_717_file-bak_20260717_142749.ppke
LocalCleanup : applied
Status       : Command completed successfully.

⚠️ Note: The suffix name of the encrypted file is .ppke

Normal Encrypted File (.ppke) Recovery

Configuration

bak.toml：

[restore_encryption]
private_key_file = "/tmp/key/ppk.key"

private_key_passphrase_env = "PPKPKPSW"

allow_prompt = true

PreCheckout

Perform application data or database backup pre-checks

ppk decrypt --input /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke --extract --output-dir /private/tmp/backup/peppykeep/test_717_file/717jm --config-home ~/.peppykeep/conf

Or enter password manually

ppk decrypt --input /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke --extract --output-dir /private/tmp/backup/peppykeep/test_717_file/717jm --prompt-for-private-key-passphrase --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action  : decrypt
Input   : /tmp
Output  : /tmp
PrivKey : <configured restore_encryption.private_key_file>
Prompt  : false
Next    : Re-run with --apply to execute.

Recover

Perform application data or database backups

ppk decrypt --input /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke --extract --output-dir /private/tmp/backup/peppykeep/test_717_file/717jm --apply --config-home ~/.peppykeep/conf

Or enter password manually

ppk decrypt --input /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke --extract --output-dir /private/tmp/backup/peppykeep/test_717_file/717jm --prompt-for-private-key-passphrase --apply --config-home ~/.peppykeep/conf

When the pre-test is successful, the output is as follows:

=== Completed ===
Action  : decrypt
Input   : /private/tmp/backup/peppykeep/test_717_file/test_717_file-bak_20260717_142437.ppke
Output  : /private/tmp/backup/peppykeep/test_717_file/717jm
PrivKey : /tmp/key/ppk.key
Status  : Command completed successfully.

Order Details Reference

• View ppk decrypt command details

Generate Key

Enter password manually

Perform the preliminary checks: §.

Perform key generation pre-check:

ppk key generate --key-home /private/tmp/key --prompt-for-passphrase

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action    : key generate
OutputDir : /private/tmp/key
Overwrite : false
Prompt    : true
Next      : Re-run with --apply to execute.

Execute Build

ppk key generate --key-home /private/tmp/key --apply --prompt-for-passphrase

On success, the output is as follows:

Input passphrase for generated private key: [hidden]
=== Completed ===
Action      : key generate
PrivateKey  : /private/tmp/key/ppk.key
PublicKey   : /private/tmp/key/ppk.pub
PasswordFile: /private/tmp/key/ppk.pwd
Permissions : chmod 600 /private/tmp/key/ppk.key && chmod 644 /private/tmp/key/ppk.pub
Status      : Command completed successfully.

Read environment variable password

Perform the preliminary checks: §.

# ⚠️ Note: Setting Environment Variables
export PPKPKPSW="123456"
ppk key generate --key-home /private/tmp/key

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action    : key generate
OutputDir : /private/tmp/key
Overwrite : false
Prompt    : false
Next      : Re-run with --apply to execute.

Execute Build

ppk key generate --key-home /private/tmp/key --apply

On success, the output is as follows:

=== Completed ===
Action      : key generate
PrivateKey  : /private/tmp/key/ppk.key
PublicKey   : /private/tmp/key/ppk.pub
PasswordFile: /private/tmp/key/ppk.pwd
Permissions : chmod 600 /private/tmp/key/ppk.key && chmod 644 /private/tmp/key/ppk.pub
Status      : Command completed successfully.

Order Details Reference

• View ppk key generate command details

Disaster Preparedness Drill

Regularly verify that backup, decryption, and recovery links are still available.

场景化步骤见 定期做恢复验证。macOS 上可配合 bak.toml 中的 [drill] / [drill.mysql] 使用，详见 bak.toml 配置说明。

Quick Examples

Download the remote encrypted backup and decrypt (the path is replaced by the actual environment):

ppk backup download-artifact --apply \
  --remote-key project-a/backup.ppke \
  --output-file /tmp/backup.ppke \
  --config-home ~/.peppykeep/conf

ppk decrypt --input /tmp/backup.ppke --output /tmp/backup.ppk --apply \
  --config-home ~/.peppykeep/conf

The commands and parameters of the MySQL Disaster Preparedness Drill are shown in the command reference (to be added to the standalone command page, you can link here).

Back to Encryption & Recovery Feature Index

Notification

This section is used to explain the configuration and use of message capabilities such as backup task alarms and webhook notifications on macOS.

The current document is to be added after alignment with the product MRD. Relevant configuration portals:

• app.toml notification configuration
• Backup Task Status and Alarms

Returns the macOS function block index

Universal Sense Backup

Generic App Backup: A common application-aware path for common workloads such as MySQL; requires a valid encrypted backup, and this document is an additional capability purchased separately.

Subscription instructions are available at Official Website Pricing.

Returns the macOS function block index

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

Dedicated Aware Backup

Dedicated App Backup: Dedicated application-aware backup for customer-specific workloads, with sales assistance for onboarding and deployment.

Standard macOS operating manuals do not apply to such customized scenarios. For evaluation, contact Contact support.

Returns the macOS function block index

Command Reference

The peppykeep/ppk command is divided into the following capabilities according to the CLI page tree:

• Login and Authorization: Bind the current device and refresh the authorization cache.
• Backup Command: Perform backup, volume backup, encryption, download, and object query.
• Recovery command: Decrypts the archive, restores a single or multiple MySQL databases.
• Cleanup command: Clean up historical backups locally or in object store by retention policy.
• Key command: Generates the key file required for backup encryption and recovery decryption.
• Upload Archive: Uploads the generated backup archive to the object store.
• Support & Diagnostics: Collect local diagnostic packages for troubleshooting.
• Encryption and decryption: Use ppk encrypt/ppk decrypt to process the archive.
• Compression and decompression: Use ppk pack/ppk extract to work with plain text archives.
• Working Asset Backup: Scan, backup, verify, and restore development working assets.

Before commands, confirm Configuration files in the default directory contains app.toml, prj.toml, and bak.toml, updated for your environment. First run without --apply, then apply.

FAQ can be compared to Backup Policy and Task Management when troubleshooting.

Login & Auth

ppk login Link the current device to your PeppyKeep account. Use for the first time, or when the local authorization cache expires and the account needs to be switched.

ppk login
ppk login --refresh

The command tries to open the browser to complete authorization; when it fails to open automatically, copy the authorization address in the output and enter the device code. Do not disclose the device code to others. After a successful login, subsequent backups, restores, and cleanups usually do not require repeated logins.

Using --refresh will clear the local authorization cache and re-authorize.

Backup Command

The peppykeep backup command group contains the following subcommands:

• backup run
• backup encrypt-artifact
• ppk encrypt
• backup upload-artifact
• backup download-artifact
• backup list-latest
• backup mysql-db-list
• backup large-dir

The common execution order is as follows:

1. Execute backup run to generate a local backup first.
2. When manual confirmation is required before uploading, execute backup upload-artifact.
3. Execute backup download-artifact when remote files need to be sampled.
4. Execute backup list-latest when you need to view the latest files in the object store.

The ‘backup large-dir’ and backup mysql-db-list are used for oversized directory volume backups and same-instance multi-library batch backups, respectively.

backup run

Perform a full backup process. Depending on the configuration, this may include application data backups, database backups, compression, encryption, uploads, and local history cleanup.

Command Format:

peppykeep backup run [OPTIONS] [--apply] [--config-home <DIR>]

Description

General

• --force: parameter reserved in the command help.
• --data-dir<DIR>: Temporarily overrideslocal.data_dirinprj.toml.
• --upload: temporary overlay is generated locally to continue uploading.
• --no-upload: temporary overwrite to keep only local files.
• --apply: really performs the backup; only checks when the parameter is not taken.
• --config-home<DIR>: configuration directory.

Backup Type Override Parameters

• --bak-type<db|app-data|db-and-app-data>: Temporarily overridespublic.bak_typeinbak.toml.
• --db-type<mysql|postgres|oracle|mongodb|sqlite|unspecified>: Temporarily overridespublic.db_typeinbak.toml.

Project Coverage Parameters

• --project-key<KEY>: Temporarily overrideslocal.prj_keyinprj.toml.
• --mysql-db-name<NAME>: Temporarily overrideslocal.mysql_db_nameinprj.toml.

MySQL Override Parameters

• --mysql-ip <IP>
• --mysql-port <PORT>
• --mysql-user-name <NAME>
• --mysql-pwd <PASSWORD>
• --mysqldump-path <PATH>

Object Storage Override Parameters

• --provider <TYPE>
• --bucket <NAME>
• --prefix <PREFIX>
• --endpoint <URL>
• --region <REGION>
• --access-key-id <KEY_ID>
• --access-key-secret <KEY_SECRET>
• --path-style

Usage Sample

peppykeep backup run --config-home additional/conf/dev
peppykeep backup run --apply --config-home additional/conf/dev
peppykeep backup run --apply --config-home /path/to/user/.peppykeep/u2-tmp --data-dir /your/data/dir
peppykeep backup run --apply --config-home /path/to/user/.peppykeep/u2-tmp --upload
peppykeep backup run --apply --config-home /path/to/user/.peppykeep/u2-tmp --no-upload
peppykeep backup run --apply --config-home additional/conf/dev --bak-type db-and-app-data --db-type mysql
peppykeep backup run --apply --config-home additional/conf/dev --project-key u2 --mysql-db-name u2db
peppykeep backup run --apply --config-home additional/conf/s3 --provider s3 --bucket <your_bucket> --endpoint https://s3.xxx-xxx.xxx.com --region xxx-xxx --path-style

Behaviour description

• Without --apply, output the project and backup type that will be executed this time.
• With --apply, enter the actual backup process.
• .ppke is generated when backup_encryption.enabled = true is enabled.
• Do not upload automatically when configured to keep only local files.
• When configured for both local and remote retention, the object store is automatically uploaded after the file is generated.
• When the override parameter is passed in, the command parameter is preferred; when it is not passed in, the configuration in prj.toml and bak.toml is read.
• Before and after uploading, provider, bucket, remote key and the target object address are output for easy checking of the results.

backup run --upload does not automatically clean up remote historical backups. Remote cleanup requirescleanup object-storageto be performed separately.

Step-by-step execution

If you need to generate an encrypted file locally, manually confirm it, and then upload it separately, you can do it in the following order:

peppykeep backup run --apply --config-home /path/to/user/.peppykeep/u2-tmp
peppykeep backup run --apply --config-home /path/to/user/.peppykeep/u2-tmp --data-dir /你的/实际目录
peppykeep backup run --apply --config-home /path/to/user/.peppykeep/u2-tmp --no-upload
peppykeep backup upload-artifact --apply --input-file /path/to/user/bak_u2/u2/你的文件名.ppke --config-home /path/to/user/.peppykeep/u2-tmp

Dependent Configuration

• prj.toml
• bak.toml
• Use backup encryption for configuration and public key files when encryption is enabled
• Use [object_storage] configuration when enabling automatic uploads

backup encrypt-artifact

This is an old command that is compatible with existing automation scripts. Use ppk encrypt to encrypt the .ppk archive to a .ppke file.

Command Format:

peppykeep backup encrypt-artifact --input-file <INPUT_FILE> [--apply] [--config-home <DIR>]

Description

• --input-file<INPUT_FILE>: Backup file path already exists, usually * .ppk.
• --apply: Really perform encryption. Only test results are output without this parameter.
• --config-home<DIR>: configuration directory for reading the encryption configuration in `bak.toml’.

Usage Sample

peppykeep backup encrypt-artifact --input-file /tmp/test_mysql_101-bak_20260320072031.ppk --config-home additional/conf/dev
peppykeep backup encrypt-artifact --input-file /tmp/test_mysql_101-bak_20260320072031.ppk --config-home additional/conf/dev --apply

Behaviour description

• Without --apply only prints which file will be encrypted and which public key will be used.
• With --apply, press the backup_encryption configuration in bak.toml to perform encryption.
• The output file is in the same directory as the input file by default, and the file name is the .ppke extension after the original file.

notice

• The command depends on backup_encryption.enabled = true.
• The command relies on a valid backup_encryption.public_key_file.
• When delete_plain_after_encrypt = true, the original plaintext file is deleted after successful encryption.

backup download-artifact

Download an existing backup file from the object store to the local.

Command Format:

peppykeep backup download-artifact --remote-key <REMOTE_KEY> --output-file <FILE> [--apply] [--config-home <DIR>]

Description

• --remote-key<REMOTE_KEY>: The object key in the object store, for example u2/your-file.ppke.
• <FILE>--output-file: Local output file path.
• --apply: Really perform the download; only the check information is output by default.
• --config-home<DIR>: configuration directory.

Behaviour description

• Outputs bucket, provider, remote key, and local output path without `--apply’.
• With --apply, read the [object_storage] configuration in bak.toml and perform the download.
• When provider = "s3", breakpoint continuation is supported.
• When the local file already exists and is smaller than the remote object, the download continues from the existing length.
• When the local file size is already equal to the remote object size, it is directly considered completed.
• The command automatically creates a parent directory for `--output-file’.

Usage Sample

peppykeep backup download-artifact --remote-key u2/u2-bak_2026_03_20_12_00_00.ppke --output-file /tmp/u2-bak_2026_03_20_12_00_00.ppke --config-home /path/to/user/.peppykeep/u2-tmp
peppykeep backup download-artifact --apply --remote-key u2/u2-bak_2026_03_20_12_00_00.ppke --output-file /tmp/u2-bak_2026_03_20_12_00_00.ppke --config-home /path/to/user/.peppykeep/u2-tmp

Continue decryption verification after download:

peppykeep backup download-artifact --apply --remote-key u2/u2-bak_2026_03_20_12_00_00.ppke --output-file /tmp/u2-bak_2026_03_20_12_00_00.ppke --config-home /path/to/user/.peppykeep/u2-tmp
ppk decrypt --input /tmp/u2-bak_2026_03_20_12_00_00.ppke --output /tmp/u2-bak_2026_03_20_12_00_00.verify.ppk --apply --config-home /path/to/user/.peppykeep/u2-tmp --prompt-for-private-key-passphrase

backup list-latest

Lists the most recent files in the object store in reverse order by last modified time.

Command Format:

peppykeep backup list-latest [--config-home <DIR>] [--prefix <PREFIX>] [--top <N>]

Description

• --config-home<DIR>: configuration directory.
• --prefix<PREFIX>: qualifies the object prefix.
• --top<N>: limit the number of output bars, default 10.

When --prefix is not passed, [object_storage] .prefix in bak.toml is used by default.

Usage Sample

peppykeep backup list-latest --config-home additional/conf/local --prefix u2/ --top 10
peppykeep backup list-latest --config-home /path/to/user/.peppykeep/u2-tmp --prefix u2/ --top 20

Output content

• LastModified
• Size
• Key

When the upload shows success, but you also want to confirm whether the object has been written to the bucket, you can use this command to check.

backup mysql-db-list

Batch backup of multiple databases in one instance of MySQL.

Command Format:

peppykeep backup mysql-db-list --request-file <FILE> [--apply] [--config-home <DIR>]

Description

• --request-file<FILE>: Request file path, supportsjsonandtoml.
• --apply: really performs the backup; only the summary is output when not imported.
• --config-home<DIR>: configuration directory. bak.toml still provides MySQL connection parameters, object storage configuration, encryption configuration, and local backup directory.

dry-run example

peppykeep backup mysql-db-list \
  --request-file ./mysql_bak_request.toml \
  --config-home /data/conf/peppykeep/mysql-bak

The output summary will include:

• RequestFile
• Instance
• DbCount
• Upload
• LocalCleanup
• RemoteCleanup
• Docker

Execution Example

peppykeep backup mysql-db-list \
  --request-file ./mysql_bak_request.toml \
  --config-home /data/conf/peppykeep/mysql-bak \
  --apply

TOML Example

instance_name = "mysql_instance_a"
upload_to_oss = true
remove_older_files = true
remove_older_oss_files = true

[base]
uuid = ""
name = "mysql_bak"
desc = "backup multiple mysql databases"

[[db_config_list]]
db_name = "db_a"
include_table_list = []
exclude_table_list = []

[[db_config_list]]
db_name = "db_b"
include_table_list = []
exclude_table_list = ["large_table_1", "large_table_2"]

JSON Example

{
  "base": {
    "uuid": "",
    "name": "mysql_bak",
    "desc": "backup multiple mysql databases"
  },
  "instance_name": "mysql_instance_a",
  "container": {
    "docker_container_name": "mysql-container-a",
    "docker_cmd_path": "/usr/bin/docker"
  },
  "db_config_list": [
    {
      "db_name": "db_a",
      "include_table_list": [],
      "exclude_table_list": []
    },
    {
      "db_name": "db_b",
      "include_table_list": [],
      "exclude_table_list": [
        "large_table_1",
        "large_table_2"
      ]
    }
  ],
  "upload_to_oss": true,
  "remove_older_files": true,
  "remove_older_oss_files": true
}

Table Filter Rules

• *: matches any length character
• ?: matches a single character
• [abc]: matches one character in the character set
• [a-z], [0-9]: matches character range

Example:

[[db_config_list]]
db_name = "db_c"
include_table_list = ["user_*", "order_2026??", "log_[0-9][0-9]"]
exclude_table_list = []

exclude_table_list does not take effect when include_table_list is not empty. When the pattern in include_table_list does not match any table, the command reports an error directly.

Behaviour description

1. Read request-file
2. Export each database in db_config_list in turn
3. Package and compress multiple .sql files
4. Configure to generate encrypted files when encryption is enabled
5. Upload object store when upload_to_oss = true
6. Clean up local history files when remove_older_files = true
7. Clean remote history files when remove_older_oss_files = true

backup large-dir

Perform volumetric archive backups of very large directories.

Command Format:

peppykeep backup large-dir <SUBCOMMAND> [OPTIONS]

Subcommand

• backup large-dir run
• backup large-dir list
• backup large-dir verify
• backup large-dir restore

run

Purpose:

• scanned directory
• Planning for Volume Breakdown
• Generate .ppk Volume Archive
• Perform volume encryption as configured
• Optional upload object storage
• Generate manifest.json' and state.json`

peppykeep backup large-dir run \
  --config-home /path/to/conf \
  --data-dir /path/to/large-dir \
  --project-key project-a \
  --chunk-size 4GiB

Real Execution:

peppykeep backup large-dir run \
  --apply \
  --config-home /path/to/conf \
  --data-dir /path/to/large-dir \
  --project-key project-a \
  --chunk-size 4GiB \
  --compress none \
  --upload

Current Supported Parameters:

• --data-dir
• --project-key
• --chunk-size
• --compress <none|gzip|zstd>
• --upload
• --resume

zstd currently retains only parameters, the execution link is not yet implemented. --resume is used to continue outstanding tasks.

list

peppykeep backup large-dir list \
  --config-home /path/to/conf \
  --project-key project-a \
  --top 10

Output Focus:

• TaskId
• Project
• Status
• Files
• Parts
• Upload
• TaskDir

verify

peppykeep backup large-dir verify \
  --config-home /path/to/conf \
  --project-key project-a

Verify by Task ID:

peppykeep backup large-dir verify \
  --config-home /path/to/conf \
  --task-id 1774341702215

The current verify only verifies the local task structure and the local volume file, not the integrity of the remote object.

restore

peppykeep backup large-dir restore \
  --config-home /path/to/conf \
  --project-key project-a \
  --output-dir /path/to/restore-out

Restore by Task ID:

peppykeep backup large-dir restore \
  --config-home /path/to/conf \
  --task-id 1774341702215 \
  --output-dir /path/to/restore-out

When you need to explicitly specify a private key and prompt for a password:

peppykeep backup large-dir restore \
  --config-home /path/to/conf \
  --task-id 1774341702215 \
  --output-dir /path/to/restore-out \
  --decrypt-private-key-file /path/to/ppk.key \
  --prompt-for-private-key-passphrase

The current restore only recovers from the local task directory and is not responsible for automatically downloading missing volumes from the remote object store.

Task Directory

<local_tmp_home>/tasks/<project-key>-<task-id>/

Common documents:

manifest.json
state.json
parts/

Among them:

• manifest.json: task meta information, volume breakdown information, file list
• state.json: execution status
• parts/: volumetric archiving and encryption products

backup upload-artifact

把已经生成好的备份文件上传到对象存储。

Command Format:

peppykeep backup upload-artifact --input-file <FILE> [--apply] [--config-home <DIR>]

Description

• --input-file <FILE>：本地已有备份文件路径，通常为 *.ppke。
• --apply：真正执行上传；默认只输出检查信息。
• --config-home<DIR>: configuration directory.

Behaviour description

• 不带 --apply 时，输出 bucket 和远端 key。
• 带 --apply 时，读取 bak.toml 中的 [object_storage] 配置并执行上传。
• 远端 key 默认按 prj_key/文件名 生成。
• [object_storage].prefix 非空时，远端 key 为 prefix/prj_key/文件名。

Dependent Configuration

• bak.toml 中的 [object_storage]
• prj.toml 中的 local.prj_key

Usage Sample

peppykeep backup upload-artifact --input-file /path/to/user/bak_u2/u2/u2-bak_2026_03_20_12_00_00.ppke --config-home /path/to/user/.peppykeep/u2-tmp
peppykeep backup upload-artifact --apply --input-file /path/to/user/bak_u2/u2/u2-bak_2026_03_20_12_00_00.ppke --config-home /path/to/user/.peppykeep/u2-tmp

与 backup run 的配合

需要先在本地生成文件、再单独上传时：

peppykeep backup run --apply --config-home /path/to/user/.peppykeep/u2-tmp --no-upload
peppykeep backup upload-artifact --apply --input-file /path/to/user/bak_u2/u2/你的文件名.ppke --config-home /path/to/user/.peppykeep/u2-tmp

ppk encrypt

将 .ppk 归档加密为 .ppke 文件。新建备份流程应使用此命令。

Command Format:

ppk encrypt --input <INPUT_FILE> --output <OUTPUT_FILE> [--apply] [--config-home <DIR>]

Description

• --input <INPUT_FILE>：待加密的 .ppk 归档文件。
• --output <OUTPUT_FILE>：加密后生成的 .ppke 文件。
• --apply：真正执行加密；不带该参数时只输出检查结果。
• --config-home <DIR>：配置目录，用于读取 bak.toml 中的备份加密配置。

Usage Sample

ppk encrypt --input /tmp/backup.ppk --output /tmp/backup.ppke --config-home /path/to/conf
ppk encrypt --input /tmp/backup.ppk --output /tmp/backup.ppke --apply --config-home /path/to/conf

Behaviour description

• 不带 --apply 时，只显示输入、输出和将使用的公钥。
• 带 --apply 时，使用 [backup_encryption] 的 public_key_file 执行加密。
• 加密成功后，是否保留 .ppk 明文归档由备份策略决定。

兼容性

历史归档 .tar.gz 和加密文件 .tar.gz.enc 仍可用于兼容恢复。已有自动化脚本可继续使用 backup encrypt-artifact，但新建流程应统一使用 .ppk、.ppke 与 ppk encrypt。

Recall command

The peppykeep restore command group currently provides:

• ppk decrypt
• restore decrypt
• restore mysql
• restore mysql-batch

It is recommended to use ppk decrypt to decrypt .ppke to .ppk before proceeding to the subsequent recovery process. restore decrypt is reserved for compatibility with existing automated scripts.

MySQL restore must use a separate [restore.mysql] target configuration and cannot reuse the [mysql] configuration of the production backup.

restore decrypt

This is an old command that is compatible with existing automation scripts. Use ppk decrypt to decrypt the .ppke backup file to a .ppk file.

Command Format:

peppykeep restore decrypt --backup-file <BACKUP_FILE> [--output-file <FILE>] [--decrypt-private-key-file <FILE>] [--prompt-for-private-key-passphrase] [--apply] [--config-home <DIR>]

Description

• --backup-file<BACKUP_FILE>: encrypts the backup file path.
• --output-file<FILE>: decrypts the output file path.
• --decrypt-private-key-file<FILE>: path to the private key file. Use the recovery private key in the configuration when not passing.
• --prompt-for-private-key-passphrase: Enter the private key password from the terminal prompt.
• --apply: really perform decryption.
• --config-home<DIR>: configuration directory.

Usage Sample

peppykeep restore decrypt --backup-file /tmp/a.ppke
peppykeep restore decrypt --backup-file /tmp/a.ppke --output-file /tmp/a.ppk --apply
peppykeep restore decrypt --backup-file /tmp/a.ppke --decrypt-private-key-file /tmp/ppk.key --prompt-for-private-key-passphrase --apply

Behaviour description

• Without `--apply’, only print which file will be decrypted, where it will be output, and which private key to use.
• Actual decryption is performed with `--apply’.

notice

• The private key password can also be provided via the environment variable PPKPKPSW.
• If the output directory does not exist, you need to create it manually first.

ppk decrypt

将 .ppke 加密归档解密为 .ppk 文件；可选在解密后直接提取归档内容。新建恢复流程应使用此命令。

Command Format:

ppk decrypt --input <INPUT_FILE> --output <OUTPUT_FILE> [--apply] [--config-home <DIR>]
ppk decrypt --input <INPUT_FILE> --extract --output-dir <DIR> [--apply] [--config-home <DIR>]

Description

• --input <INPUT_FILE>：待解密的 .ppke 文件。
• --output <OUTPUT_FILE>：解密后生成的 .ppk 文件。
• --extract：解密完成后直接提取归档内容。
• --output-dir <DIR>：使用 --extract 时的提取目标目录。
• --apply：真正执行解密；不带该参数时只输出检查结果。
• --config-home <DIR>：配置目录，用于读取恢复解密配置。

Usage Sample

ppk decrypt --input /tmp/backup.ppke --output /tmp/backup.ppk --apply --config-home /path/to/conf
ppk decrypt --input /tmp/backup.ppke --extract --output-dir /tmp/restore --apply --config-home /path/to/conf

Behaviour description

• 使用 [restore_encryption] 的 private_key_file 进行解密。
• 私钥受口令保护时，可按运行环境的安全方式提供口令。
• 解密或提取到生产环境前，应先在隔离目录验证归档内容。

兼容性

历史 .tar.gz.enc 和过渡期 .ppk.enc 文件仍可用于兼容解密。已有自动化脚本可继续使用 restore decrypt，但新建流程应统一使用 .ppke、.ppk 与 ppk decrypt。

restore mysql

peppykeep restore mysql Restore the local backup to a standalone MySQL target library. Only local backup files are supported; remote objects should be downloaded to the local machine first.

peppykeep restore mysql \
  --backup-file /data/backups/app.ppke \
  --target-db-name app_restore \
  --config-home /path/to/conf

Add --apply after confirming dry-run. Restore must use a separate [restore.mysql] configuration in bak.toml, prohibiting multiplexing of production [mysql] connections. To delete a target library, you must also provide --drop-target-db and exactly ‘–confirm-target-db’.

It is recommended to execute in a standalone recovery environment and leave the workspace for troubleshooting by default.

restore mysql-batch

ppk restore mysql-batch Recovers multiple SQL files from one MySQL backup archive and imports the specified target libraries separately.

ppk --config-home /path/to/conf \
  restore mysql-batch \
  --backup-file /data/backups/app.ppke \
  --db-map source_db:restore_db

After confirming the backup file, library mapping, destination address and workspace of dry-run, add --apply. The command writes to the target MySQL and must be configured with a separate [restore.mysql]. When deleting an existing target library, provide --confirm-target-db for each target library for --drop-target-db.

.ppke, .ppk, .tar.gz.enc, and .tar.gz are all available as inputs; the encrypted archive is automatically decrypted before recovery.

Clean command:

The peppykeep cleanup command group contains:

• cleanup local
• cleanup object-storage

backup run --upload does not automatically clean up remote historical backups. Execute cleanup object-storage separately when you need to clean up old files in the object store.

cleanup local

Clean up old local backup files.

Command Format:

peppykeep cleanup local [--force] [--apply] [--config-home <DIR>]

Description

• --force: parameter reserved in the command help.
• --apply: Really delete local old backup files.
• --config-home<DIR>: configuration directory.

Usage Sample

peppykeep cleanup local --config-home additional/conf/local
peppykeep cleanup local --apply --config-home additional/conf/local

Behaviour description

• Without `--apply’, only the local files scheduled for deletion this time are output.
• With --apply, delete local historical backups by retention policy.

cleanup object-storage

Purge historical backup objects in the object store according to the remote retention policy of the current project.

OSS is not currently exposed as an independent external capability. The public command usescleanup object-storage; cleanup oss is just a historically compatible alias that has been hidden in the command help and is not recommended for continued use in manuals and new scripts.

Command Format:

peppykeep cleanup object-storage [--force] [--apply] [--config-home <DIR>]

Compatible entrances:

peppykeep cleanup oss [--force] [--apply] [--config-home <DIR>]

Description

• --apply: Perform the cleanup process. Only the dry-run summary is output without this parameter, no object storage is connected, and no remote objects are listed or deleted.
• --force: Really delete the object to be cleaned. Only takes effect when --apply is taken at the same time; when --force is not taken, only the object to be deleted is output in the log even if the cleanup process is entered.
• --config-home<DIR>: configuration directory for reading bak.toml' and prj.toml`.

Configuration Source

• [object_storage] of bak.toml provides object storage connection configuration. The current implementation supportsprovider = "oss"andprovider = "s3".
• The [local] prj_key of ’prj.toml` decides to clean up only the objects under the current project.
• The [remote.retain] of prj.toml determines the retention policy for remote backups.

The object-key scan scope is formed from [object_storage].prefix and prj_key:

<prefix>/<prj_key>/

When prefix is empty, the scan range is:

<prj_key>/

Usage Sample

First review the configuration and action summary:

peppykeep cleanup object-storage --config-home additional/conf/local

Enter the object-storage cleanup flow, but only log the objects that would be deleted; do not delete anything:

peppykeep cleanup object-storage --apply --config-home additional/conf/local

After confirming the objects to delete, perform the deletion:

peppykeep cleanup object-storage --force --apply --config-home additional/conf/local

Cleanup logic

1. Read prj.toml to obtain the current project prj_key and [remote.retain] settings.
2. Read bak.toml and create the object-storage client. The command fails if object storage is disabled or the provider, bucket, or credentials are missing.
3. Calculate the set of dates to retain:
   • Today.
   • Each value in remote.retain.days maps to a historical calendar date.
   • The 1st day of each month for the most recent remote.retain.months months.
   • Each year in remote.retain.years maps to January 1 of that historical year.
4. List objects under <prefix>/<prj_key>/.
5. Parse backup dates from object names. .ppke uses the matching .ppk name; strip .enc before parsing.
6. Objects matching retention dates are kept; others are marked for deletion.
7. When multiple objects match retention on the same day, keep only the newest; others go to the delete list.
8. If pending deletes would drop below remote.retain.minimum_retain_count, clear the delete list.
9. If the object date is within remote.retain.minimum_retain_date_count days of today, keep it—do not delete.
10. Objects whose dates cannot be parsed from backup naming rules go to the manual list; they are not auto-deleted.

Deletion criteria

The object-storage delete API is called only when all of the following conditions are met:

• The command includes --apply.
• The command includes --force.
• The object is within the current project scan scope.
• Object name encodes the backup date.
• Object is not covered by any retention policy.
• Object is not protected by minimum retain count or days.

Objects that do not qualify are kept, marked for deletion, or listed in manual for human review.

Key Command

The ppk key command group generates, verifies, and packages recovery keys. This manual covers:

• key generate
• key check
• key export-recovery-kit
• key verify-recovery-kit
• key print-recovery

Standard key directory contains:

• ppk.pub: public key used for backup
• ppk.key: private key used for restore
• ppk.pwd: passphrase file—only when you explicitly choose file-based passphrases
• manifest.json: non-sensitive metadata

Backup nodes keep only the public key; restore nodes keep the private key and passphrase material. Prefer --key-home for the standard key directory; legacy backup_recipient.pub / backup_recipient.key remain supported.

key generate

Generate a standard key directory for backup encryption:

• ppk.pub
• ppk.key
• ppk.pwd
• manifest.json

Command Format:

ppk key generate [--key-home <DIR>] [--force] [--prompt-for-passphrase] [--apply]

Description

• --key-home <DIR>: standard key directory.
• --force: overwrite existing key files.
• --prompt-for-passphrase: enter the private-key passphrase in the terminal.
• --apply: actually write key files.

Usage Sample

ppk key generate --key-home ~/.peppykeep/keys/project-a
PPKPKPSW='your-passphrase' ppk key generate --key-home ~/.peppykeep/keys/project-a --apply
ppk key generate --key-home ~/.peppykeep/keys/project-a --prompt-for-passphrase --apply

notice

• Without --apply, only print files and paths that would be created.
• Without --prompt-for-passphrase, provide the private-key passphrase via PPKPKPSW.
• Backup nodes store the public key only; restore nodes store the private key.

ppk key check

Verify ppk.key and ppk.pwd in the standard key directory match and the private key unlocks.

Command Format:

ppk key check --key-home <DIR>
ppk key check --private-key-file <FILE> --private-key-pwd-file <FILE>

Usage Sample

ppk key check --key-home ~/.peppykeep/keys/project-a
ppk key check --private-key-file /Volumes/PPK_SAFE/keys/project-a/ppk.key \
  --private-key-pwd-file /Volumes/PPK_SAFE/keys/project-a/ppk.pwd

Checks show file presence, checksums, and match results—not private keys or passphrases. Fix the key directory before restore if files are missing, passphrases mismatch, or permissions fail.

ppk key export-recovery-kit

Generate a recovery kit for offline media, USB storage, or safe deposit.

Command Format:

ppk key export-recovery-kit \
  --key-home <KEY_HOME> \
  --output-dir <OUTPUT_DIR> \
  --apply

Usage Sample

ppk key export-recovery-kit \
  --key-home ~/.peppykeep/keys/project-a \
  --output-dir /Volumes/PPK_SAFE/recovery-kits/project-a \
  --apply

Output includes ppk.pub, ppk.key, ppk.pwd, manifest.json, checksums.sha256, and recovery instructions. Output directory must be empty or missing; do not upload kits to shared folders or log passphrases.

ppk key verify-recovery-kit

Verify recovery kit file integrity, key/passphrase pairing, and optional real-backup decrypt.

Command Format:

ppk key verify-recovery-kit --kit-dir <DIR>
ppk key verify-recovery-kit --kit-dir <DIR> --backup-file <FILE>

Usage Sample

ppk key verify-recovery-kit \
  --kit-dir /Volumes/PPK_SAFE/recovery-kits/project-a

ppk key verify-recovery-kit \
  --kit-dir /Volumes/PPK_SAFE/recovery-kits/project-a \
  --backup-file /data/backup/sample.ppke

Validation checks required files, checksums.sha256, ppk.key, and ppk.pwd; with a backup sample it also verifies decrypt. Do not use a failed kit for production restore.

ppk key print-recovery

Generate recovery materials suitable for offline storage.

Command Format:

ppk key print-recovery \
  --key-home <KEY_HOME> \
  --output-dir <OUTPUT_DIR> \
  --apply

Usage Sample

ppk key print-recovery \
  --key-home ~/.peppykeep/keys/project-a \
  --output-dir ./printable-recovery \
  --apply

Output includes public key, private key, passphrase, manifest, and recovery instructions. Print and store ppk.key and ppk.pwd separately; cover sheets record purpose, key ID, date, and checksum—not key material.

Upload archive

peppykeep backup upload-artifact uploads an existing archive to object storage—ideal for generate-locally, review, then upload workflows.

peppykeep backup upload-artifact \
  --input-file /path/to/backup.ppke \
  --config-home /path/to/conf

After dry-run confirms bucket, object key, and paths, add --apply to upload:

peppykeep backup upload-artifact \
  --input-file /path/to/backup.ppke \
  --config-home /path/to/conf \
  --apply

Reads [object_storage] in bak.toml and project settings in prj.toml. See backup upload-artifact for parameters and walkthrough.

Support & Diagnostics

ppk support collects local diagnostics to troubleshoot sign-in, authorization, config, or command failures.

ppk support collect
ppk support collect --output-dir /tmp/ppk-support-diag

Diagnostics bundles include recent events, errors, and environment summary. Redact paths, accounts, and config before submitting via Contact support.

ppk support upload is a reserved upload entry point; availability is shown in the current CLI --help.

Recovery Drill

ppk drill mysql is a MySQL recovery drill separate from production restore. It verifies decrypt, unpack, import, and app data dirs in isolation; it does not overwrite production by default.

Command Format:

ppk drill mysql \
  --project-key <PROJECT_KEY> \
  --backup-file <BACKUP_FILE> \
  [--target-db-name <TARGET_DB_NAME>] \
  [--config-home <CONFIG_HOME>] \
  [--apply]

Without --apply, only print the drill plan—no download, decrypt, unpack, or DB import. Confirm target DB, workspace, and keys first:

ppk drill mysql \
  --project-key project-a \
  --backup-file /data/backups/project-a.ppke \
  --target-db-name ppk_drill_project_a \
  --config-home /etc/peppykeep/conf \
  --prompt-for-private-key-passphrase \
  --apply

General

• --project-key: override the project id in config.
• --backup-file: local .ppk / .ppke, also .tar.gz / .tar.gz.enc; remote objects must be downloaded first.
• --target-db-name: drill target database; defaults to ppk_drill_<project>_<timestamp>.
• --workspace-dir: workspace for download, decrypt, unpack, and reporting.
• --decrypt-private-key-file: private key used for encrypted artifacts.
• --check-sql-file: custom SQL validation script.
• --keep-workspace: keep the workspace on success; on failure it is kept by default for troubleshooting.
• --drop-target-db --confirm-target-db <NAME>: drop the drill DB only after explicit confirmation.

Drill phase

1. Verify authorization and inputs.
2. Prepare an isolated workspace.
3. Decrypt the artifact, then unpack the archive.
4. Inspect summaries under ppk_data/sql/, ppk_data/data/, etc.; legacy layouts use data/sql/ and data/data/.
5. Import the SQL dump into an isolated drill database.
6. Run default or custom SQL checks; output JSON/text reports.

Drills do not in-place restore production, restart apps, or perform full DR failover. Log duration, missing dependencies, permission issues, and reports regularly.

Encryption and decryption

PeppyKeep uses .ppk for plaintext archives and .ppke for encrypted ones. New flow: ppk encrypt / ppk decrypt; backup encrypt-artifact and restore decrypt remain for legacy automation.

ppk encrypt --input backup.ppk --output backup.ppke --apply
ppk decrypt --input backup.ppke --output backup.ppk --apply

Encryption needs the public key; decryption needs the private key. Pass passphrases via env vars or the terminal—never shell history, scripts, or tickets. Dry-run without --apply first to confirm inputs, outputs, and key paths.

See ppk encrypt and ppk decrypt for parameters.

Compression and decompression

ppk pack archives files or directories to .ppk; ppk extract unpacks .ppk or compatible .tar.gz. Neither handles encryption.

ppk pack --input ./data --output data.ppk --apply
ppk extract --input data.ppk --output-dir ./data-out --apply

ppk pack accepts files or directories (default .ppk output). ppk extract accepts .ppk and legacy .tar.gz; creates the output directory if needed.

ppk pack --input ./data --output data.ppk --overwrite --apply
ppk extract --input data.ppk --list
ppk extract --input data.ppk --output-dir ./data-out --overwrite --apply

Existing outputs and non-empty directories are not overwritten. Decrypt .ppke via Encryption with ppk decrypt to .ppk, then ppk extract; or use ppk decrypt --extract in one step.

Reject absolute paths and path traversal on extract so archives cannot escape the target directory.

Backup of working assets

ppk work-assets backs up personal dev work assets—dotfiles, app config, small local data—not production system paths like /etc.

Standard flow: scan and review the plan, then run backup and restore:

ppk work-assets scan --home /path/to/home --asset-set-key default
ppk work-assets apply --asset-set-key default --apply
ppk work-assets verify --asset-set-key default
ppk work-assets restore preview --asset-set-key default
ppk work-assets restore run --asset-set-key default --apply

Before scan/restore, review include, exclude, skip, and reasons; writes require --apply. macOS work-assets flow: Work Assets backup.

Desktop UI

The desktop UI is in development and not yet stable. Planned for Windows and macOS; no Linux desktop app.

Linux is CLI-only but can be driven from Windows or macOS desktop clients. Until the desktop app ships, follow this manual’s CLI guides and command reference.

Current recommendation

Recommended way to stand up backups today:

1. Use templates in this manual to create and verify app.toml, bak.toml, prj.toml, and related config.
2. Or use a dedicated test machine and have AI assist with full setup and first-backup validation.
3. On a test machine, verify backup, restore, encryption, upload, and cleanup; re-check paths, permissions, object storage, and keys in config.
4. After validation, promote config to production (without test-only secrets) for critical data and app backups.

Do not let AI run unreviewed config changes or destructive --apply commands in production. When migrating config, replace hosts, accounts, keys, and object storage credentials, then dry-run again.

Desktop app vs. CLI

The desktop app is the visual entry on Windows and macOS; Linux hosts run the CLI and can be managed backup nodes. Whichever entry you use, validate config and results against the command reference.

FAQ

For job failures, upload errors, or restore errors, start here; if unresolved see Contact support.

Backup failed but the failing step is unclear—what now?

See whether the job stopped at local packaging, upload, encryption, or MySQL export, then cross-check task results and common states and config. Common checks:

• Whether backup source paths are correct
• Default config directory exists and all three TOML files are tuned for your environment (see Configuration files)
• Whether the output directory is available
• Whether object storage is configured correctly
• Whether the MySQL connection parameters are correct
• Whether MySQL TLS verification failed

If the task shows Partial success, review what was skipped and which steps did not finish (see Why “Partial success”?).

Why does the task show “Partial success”?

Partial success means the job finished but some items failed or were skipped by rules. Common cases:

• Some source paths are not accessible
• Some content was filtered by exclusion rules
• A step in upload, encryption, or cleanup did not finish

Identify which phase failed, then re-check source paths, filters, or upload settings.

Local backup exists but nothing in object storage—what now?

Check first:

• Whether this run used --no-upload
• Whether the upload command actually used --apply
• Whether [object_storage] is fully configured
• Whether provider, bucket, prefix, endpoint, and region are correct

If the local file was created but not uploaded, run backup upload-artifact separately.

Cannot see or download files in object storage—what now?

Check first:

• Whether the upload succeeded
• Whether the remote key follows prefix/prj_key/filename
• Whether bucket, prefix, and region match the current configuration
• Whether the target file was removed by remote retention cleanup

To verify a remote artifact, run backup download-artifact, then ppk decrypt for a decrypt check.

Remote backup history keeps growing—what now?

backup run --upload does not prune remote history. Run cleanup object-storage separately if objects accumulate.

Verify before you run:

• bucket
• prefix
• Retention rules

Run dry-run before the first execution, then decide whether to add --apply.

Incomplete restore or missing directories—what to check first?

Common causes include:

• The current plan never included this directory or dataset
• Backup source was excluded by exclusion rules
• Wrong restore point selected
• Unverified backup file used
• Encrypted archive not decrypted first

For file or directory restores, recover to a staging path first, then verify content, permissions, and ownership.

Table filters not applied in multi-DB backup—what now?

First check rules in mysql_bak_request.toml:

• Whether include_table_list is non-empty
• Whether exclude_table_list still applies
• Whether glob rules actually match the target tables

Note:

• When include_table_list is non-empty, exclude_table_list is ignored
• If include_table_list matches no tables, the command fails immediately

Backup size much larger than expected—check what first?

First check whether the backup included all of the following:

• View Log Entry
• Temp Directory
• Cache directory
• Build Product
• Regenerable intermediate files

For complex rules, start with backup scope and exclusions and validate a few critical paths.

Could cleanup delete files you still need to restore?

Run dry-run before the first execution, then add --apply if needed. For object storage cleanup, verify bucket, prefix, and retention rules. Commands: cleanup local, cleanup object-storage.

Restore failed (private key, passphrase, or output dir)—what now?

Common causes include:

• Private key missing or path incorrect
• Wrong private-key passphrase (see Prerequisites · encrypted restore)
• Corrupt or incomplete backup download
• Decrypted output directory unavailable

Create the restore directory if missing. Decryption: ppk decrypt.

In container_exec mode, should MySQL port be inside or outside the container?

For container mysql_container_instance_a with host-mapped MySQL port 3506: in container_exec mode the client runs inside the container, so connect to 127.0.0.1:3306 inside the container—not host port 3506.

Collect local diagnostics

Perform the preliminary checks: §.

peppykeep support collect --config-home "%USERPROFILE%\.peppykeep\conf"

When the pre-test is successful, the output is as follows:

=== Dry Run ===
Action      : support collect
SupportDir  : C:\Users\admin\.peppykeep\support
SnapshotDir : C:\Users\admin\.peppykeep\support\diag-20260717_110301
EventsLog   : C:\Users\admin\.peppykeep\support\events.jsonl
Next        : Re-run with --apply to execute.

Run diagnostics

peppykeep support collect --apply --config-home "%USERPROFILE%\.peppykeep\conf"

On success, the output is as follows:

=== Completed ===
Action      : support collect
SupportDir  : C:\Users\admin\.peppykeep\support
SnapshotDir : C:\Users\admin\.peppykeep\support\diag-20260717_105701
Status      : Command completed successfully.

Order Details Reference

• support collect

Coming soon

Security Best Practices

How to protect backup encryption keys, object storage credentials, database passwords, and app tokens when using peppykeep.

Separate recovery keys from runtime credentials

Treat recovery keys and runtime credentials as two separate material classes:

恢复密钥：ppk.pub、ppk.key、PPKPKPSW（私钥口令）
运行时凭证：S3 兼容对象存储凭证、数据库密码、应用令牌

Recovery keys protect encrypted backups. Runtime credentials let peppykeep reach object storage, databases, or app APIs. Store, authorize, and rotate them separately.

Recovery key management

ppk.pub is the backup-source public key. You may deploy it to backup hosts or config management, but do not publish it on the public internet.

ppk.key is the restore private key—store it only on restore hosts or trusted ops environments, not on every backup source.

PPKPKPSW holds the private-key passphrase. Provide it via secure env vars or interactive input—never commit it to config. If both private key and passphrase are lost, backups are unrecoverable.

Recommended Linux permissions:

chmod 600 /etc/peppykeep/keys/<key-purpose>/ppk.key

Recommended macOS permissions:

chmod 600 ~/.peppykeep/keys/<key-purpose>/ppk.key

Small-team practices

Individuals or teams of 1–3:

• Keep ppk.key separate from the private-key passphrase.
• Keep at least one offline copy (paper record or encrypted USB).
• Do not store passphrases on a single personal machine only.
• Prefer env vars or key files for object storage and DB passwords.
• Verify an encrypted test backup at least every 6–12 months.

Teams of 3–20:

• Assign different owners for ppk.key and the private-key passphrase.
• Record each key’s purpose, owner, creation date, and affected systems.
• Use accounts scoped to a single bucket or prefix.
• Use dedicated accounts for database backup and restore.
• Rotate runtime credentials on a schedule.
• Run recovery drills after onboarding and after credential changes.

Larger teams:

• Manage runtime credentials with a secrets manager, Vault, Kubernetes Secrets, cloud KMS, or vendor key services.
• Prefer IAM/RAM roles and temporary credentials over long-lived access keys.
• Use dual control or approval for recovery private keys.
• Audit access, copy, rotation, and destruction of ppk.key and passphrases.
• Split object storage permissions by env, system, bucket, and prefix.
• Run at least one recovery drill per quarter on mission-critical systems.

Object storage credentials

Use scoped sub-accounts or roles for S3-compatible storage; never use the cloud root access key.

Recommended setup:

[object_storage]
provider = "s3"
access_key_id_env = "PPK_S3_ACCESS_KEY_ID"
access_key_secret_env = "PPK_S3_ACCESS_KEY_SECRET"

Environment variable example:

export PPK_S3_ACCESS_KEY_ID="<access-key-id>"
export PPK_S3_ACCESS_KEY_SECRET="<access-key-secret>"

Grant least privilege by workflow:

Permission names depend on your cloud provider.

Database password

Use dedicated DB accounts for backup and restore; do not run daily backups as root or admin.

Use a dedicated MySQL backup user; pass passwords via env vars or key files:

[mysql]
user = "ppk_backup"
password_env = "PPK_MYSQL_PASSWORD"

Or:

[mysql]
user = "ppk_backup"
password_file = "/etc/peppykeep/secrets/mysql.pwd"

Environment variable example:

export PPK_MYSQL_PASSWORD="<mysql-password>"

Apply the same pattern to PostgreSQL, Redis, MongoDB, and app APIs: dedicated accounts/tokens with least privilege for backup/restore only.

Key files

If you are not using a secrets manager, store key files in a dedicated directory with tight permissions.

Linux example:

/etc/peppykeep/secrets

macOS example:

~/.peppykeep/secrets

Recommended permissions:

chmod 700 /etc/peppykeep/secrets
chmod 600 /etc/peppykeep/secrets/*.toml
chmod 600 /etc/peppykeep/secrets/*.pwd

Never commit key files to git, shared drives, screenshots, tickets, or backup artifacts.

Redact logs and screenshots

Redact secrets before sharing logs, screenshots, commands, or config snippets with support.

May include:

• Configuration key names.
• Environment variable names.
• Key file paths.
• Host, port, database name, and username—only if these are not sensitive in your environment.
• Error summary.
• peppykeep version, OS, and install method.

Must redact:

• Plaintext passwords.
• Access key secret。
• API token。
• Full connection strings with passwords.
• Contents of ppk.key.
• The actual PPKPKPSW value or private-key passphrase.

Redaction example:

MySQL connection failed.
Mode: container_exec
Host: 192.0.2.10
Port: 3306
User: ppk_restore
Password: <hidden>

Rotation and recovery drills

Rotate runtime credentials after personnel changes, suspected leaks, or environment changes; set a cadence based on your risk tier.

Validate before you need a real restore:

• Confirm ppk.key and passphrase decrypt a test backup.
• Confirm object storage credentials can upload and download.
• Confirm the DB account still has required backup/restore privileges.
• Restore to a staging location first, then verify content and permissions.

Suggested minimum frequency:

Quick checklist

• ppk.pub is deployed on the backup source.
• Store ppk.key only on restore hosts or trusted environments.
• Manage private-key passphrases separately from ppk.key.
• Offline recovery key copies exist and were tested.
• Use scoped sub-accounts, roles, or least-privilege access keys for object storage.
• Use dedicated accounts for database backup and restore.
• Passwords and tokens are not stored in plaintext in main config files.
• Key file permissions are locked down.
• Logs, screenshots, tickets, and chat must not contain real keys.

Legal & Privacy

• Terms of Service
• Privacy Policy

Contact support

Before opening a ticket, read FAQ and the command reference. If help-center steps still fail, contact support below.

• Email: support@peppykeep.com

For billing or subscription issues, include order ID and account identifier. See Pricing.

Release notes

Release notes for the peppykeep help center. Installers and updates: PeppyKeep downloads.

Current version

• Doc version: 26.9.300 (stable)
• Product version: peppykeep 26.8.600

Earlier versions

Release notes evolve with the product. For a specific installer, contact support.

Related links

• Install and get started
• Product Overview
• peppykeep command reference