# BackupSet JSON reference

A backup set is a JSON file. Pass it to any command via `--set` (short form `-s`); otherwise the roaming default set at `%APPDATA%\ArchivstDesktop\defaultset.json` (or the directory set with `config set-default-backupset`) is used. Agents can read it to inspect state and use the [`folders` subcommands](/manual/archivstcli#cli-folders) to modify it.

## Top-level fields

| Property | Meaning |
|---|---|
| `Folders` | Array of folder entries (each is a folder object, described below). The core of the set. |
| `ScheduleEnabled` | `true` = automatic/scheduled backups are enabled for this set. |
| `TotalFiles` | Cumulative count of all files the set manages. |
| `TotalBytes` | Cumulative byte size of all files the set manages. |
| `TotalFilesOnline` | How many tracked files have already been synced to their destination. |
| `TotalBytesOnline` | How many tracked bytes have already been synced. |
| `LastBackup` | Timestamp of the last completed backup run. |
| `Hydration` | Map of folder key → `RestorationState` (`Archived`, `Hydrating`, `Hydrated`) tracking each folder's rehydration (restore) progress. |
| `HydrationStartTimes` | Map of folder key → timestamp, when that folder's rehydration started. |

## Folder entry fields

Each folder in the set carries the following options, grouped by purpose.

### Identity

| Property | Meaning |
|---|---|
| `FolderName` | Folder name. Every `/` and `\` is stripped on write, so this is always a single leaf name, never a path. |
| `Path` | Local source path of the folder. |
| `DisplayName` | Label shown in the UI (defaults to the name). |
| `UniqueId` | GUID that uniquely identifies this folder (used for encryption keys and hydration tracking). |
| `Selected` | `true` = this folder is currently included in backups. |
| `Selectable` | `true` (default) = the folder's `Selected` can be toggled. |
| `IsVisible` | `true` (default) = folder appears in UI lists when filtering is applied. |

### Destination

Exactly one of `IsLocal`, `IsCloud`, or `IsFtp` is intended to be the meaningful `true`.

| Property | Meaning |
|---|---|
| `IsLocal` | Destination is a local drive. |
| `IsCloud` | Destination is the cloud. |
| `IsFtp` | Destination is an FTP server. |
| `IsArchivedCloud` | Cloud copy is stored as archived (cold) storage. |
| `IsHydratedCloud` | Cloud copy is currently hydrated (warm/active). |
| `FtpDomain` | FTP host/domain (only when `IsFtp`). |
| `FtpPath` | Path within the FTP endpoint (only when `IsFtp`). |
| `FtpUser` | FTP login name (only when `IsFtp`). |
| `DestinationExclusiveToArchivst` | `true` (default) = the destination is dedicated to Archivst and should not be shared. |

### Encryption

The encryption key itself is never stored in this JSON — only the flags below are persisted.

| Property | Meaning |
|---|---|
| `IsEncrypted` | `true` = content is encrypted at rest. |
| `IsUserEncryption` | `true` = encrypted with a user-supplied password; `false` = an Archivst-managed key. |

### Selection and filtering

| Property | Meaning |
|---|---|
| `Wildcards` | List of glob patterns. Entries starting with `/` are folder patterns; all others are file patterns. |
| `UseWildcard` | `true` = apply `Wildcards`; `false` (default) = back up everything. |
| `WildcardsAlways` | Patterns that are always enforced, regardless of `UseWildcard`. |
| `UseAlwaysWildcard` | `true` = also apply the `WildcardsAlways` list. |
| `AutoSelectFiles` | `true` = automatically select files newer than the age window below. |
| `AutoSelectDaysAge` | Age window in days for auto-selection (default `1`). |

### Image handling

| Property | Meaning |
|---|---|
| `AutoCompressImages` | Master switch for compressing images before upload. |
| `AutoCompressFormat` | Target format code (default `1`). |
| `AutoCompressQuality` | Quality setting (`0` = library default). |
| `AutoCompressIgnoreSize` | Skip compression for images larger than this size (`0` = no limit). |
| `AutoCompressMaxRes` | Maximum resolution to compress down to (`0` = no cap). |
| `AutoCompressVerify` | `true` (default) = verify the compressed image still matches the original. |
| `AutoCompressMinPsnr` | Minimum peak-signal-to-noise ratio to accept (default `25.0`). |
| `AutoCompressMinSimilarity` | Minimum normalized similarity to accept (default `0.90`). |
| `OnlyRaw` | Only back up original-format images (skip processed variants). |
| `FallbackCompressionFailure` | If compression fails, fall back to copying the original. |
| `HasFailedImageConversions` | `true` = at least one image conversion failed for this folder. |

### Duplicates

| Property | Meaning |
|---|---|
| `DuplicateFileHandling` | `Copy` (default) = always copy duplicate files; `Ignore` = skip duplicates. |

## Example set

```json
{
  "ScheduleEnabled": false,
  "TotalFiles": 4821,
  "TotalBytes": 9876543210,
  "TotalFilesOnline": 4821,
  "TotalBytesOnline": 9876543210,
  "LastBackup": "2026-09-01T18:30:00",
  "Folders": [
	{
	  "FolderName": "Photos",
	  "Path": "D:\\Photos",
	  "Selected": true,
	  "IsCloud": true,
	  "IsEncrypted": true,
	  "IsUserEncryption": false,
	  "AutoCompressImages": true,
	  "AutoCompressVerify": true,
	  "DuplicateFileHandling": "Copy"
	}
  ]
}
```

## Excludes and skip markers

Per-file behaviour is stored as marker files under `%APPDATA%\ArchivstDesktop\`, not inside the JSON. Manage them with the [`folders` commands](/manual/archivstcli#cli-folders):

- `exclude-add` / `exclude-remove` — exact file excludes
- `skip-create` / `skip-remove` — similarity-verification skips
- `skipconvert-create` / `skipconvert-remove` (with `--reason`) — entries that must be copied as-is after a failed conversion
- `folders failed` — list conversions that failed

[Back to Agentic Usage](/agentic)