Markdown source: backupset-json.md · raw

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 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

{
  "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:

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