Archivst CLI Manual

Complete setup and command reference on how to use Archivst.CLI

Download BinaryCommand reference
Last updated:

Setup

  1. Download Archivst.CLI from your Archivst account downloads page.
  2. Binaries can be ran from any location
  3. Open a terminal in the install folder (or add the CLI executable to your PATH).
  4. Run archivst help to confirm the command is available.
  5. Sign in with archivst auth login before cloud operations such as restore request, key fetch, and update.

Archivst CLI supports one-shot mode with -c, command-argument mode without -c, and interactive shell mode when started with no arguments.

  • archivst -c backup --folder Photos runs once and exits.
  • archivst backup --folder Photos also runs once and exits.
  • archivst opens interactive prompt (archivst>) where you can run commands repeatedly.

Configuration and files

CLI mode prefers a local appsettings.json next to the executable when present. Otherwise, roaming profile settings are used. Backup set operations default to defaultset.json in the configured backup set directory.

  • Default settings path: %APPDATA%\ArchivstDesktop\appsettings.json
  • Default backup set path: %APPDATA%\ArchivstDesktop\defaultset.json
  • Configurable directory: config set-default-backupset --dir <path>

Top-level command reference

Archivst.CLI top-level commands are:

backup, restore, folders, logs, auth,

config, decrypt, keys, update, help, man, login

Common pattern: commands that support backup set input use --set (alias -s) to select a JSON backup set file.

backup

Run backup for all folders in the set, or one named folder.

  • --set, -s: path to BackupSet JSON file.
  • --folder, -f: single folder name to run; if omitted, all folders run.
  • --threads: override copy thread count for this run.
  • --quiet, -q: minimal output (spinner and counts).
  • --verbose, -v: print each completed file path.
  • --encrypted: mark destination as encrypted and provision key when needed.
  • --password: encryption password used when saving key to cloud.
  • --ftp-pass: FTP password for the folder (otherwise prompts if needed).

Example: archivst -c backup --set C:\sets\defaultset.json --folder Photos --threads 4 --quiet

restore

Restore includes three subcommands: request, poll, and run.

restore request

Request a restore for a specific folder so cloud services can prepare the hydrated data.

  • --folder, -f (required): folder name to restore.
  • --from: optional point-in-time restore value (ISO8601 or supported relative format).
  • --code: optional confirmation code from email; prompts when omitted.
  • --set, -s: backup set path.

Example: archivst -c restore request --folder Projects --from 2026-02-24T12:00:00Z --set C:\sets\cloud.json

restore poll

Poll a pending restore request to watch for completion or progress updates.

  • --folder, -f (required): folder to poll.
  • --set, -s: backup set path.
  • --interval: poll interval in seconds (default 30).
  • --timeout: optional timeout in minutes.

Example: archivst -c restore poll --folder Projects --set C:\sets\cloud.json --interval 20 --timeout 90

restore run

Copy hydrated files to a destination once the restore request has been fulfilled.

  • --folder, -f (required): folder to copy from hydrated state.
  • --set, -s: backup set path.
  • --dest, -d: destination path; if omitted, CLI uses BackupSet mapping when available.
  • --threads: override restore threads.
  • --quiet, -q: minimal progress output.
  • --verbose, -v: print each restored file path.
  • --encrypted: destination uses encryption.
  • --password: encryption password for destination setup/use.
  • --ftp-pass: FTP password for folder destination when required.

Example: archivst -c restore run --folder Projects --set C:\sets\cloud.json --dest D:\Restores --threads 2 --verbose

folder

Manage folder entries, exclusions, and skip markers in a BackupSet.

folders list

List the folders currently defined in the active backup set.

  • --set, -s: backup set path.
  • --folder, -f: optional single folder filter.
  • --verbose, -v: show summary details instead of just paths.

folders add

Add a new folder entry to the backup set with its local path and selection state.

  • --set, -s: backup set path.
  • --name: folder display name to add.
  • --path: local folder path.
  • --select: selected flag (default true).

folders test

Validate that the named folder exists and is accessible from the system running the CLI.

  • --set, -s: backup set path.
  • --name: folder name to test for existence/access.

folders update

Change the path or selection flags for an existing folder without re-adding it.

  • --set, -s: backup set path.
  • --name: folder name to update.
  • --path: optional replacement folder path.
  • --selected: optional selected state (true/false).

folders remove

Remove a folder entry so it will no longer be part of backups.

  • --set, -s: backup set path.
  • --name: folder name to remove.

folders failed

Inspect or scope folders that failed conversion during the last run.

  • --set, -s: backup set path.
  • --folder, -f: optional folder scope.
  • --path: optional relative path under failed conversions root.

folders skip-create / folders skip-remove

Mark specific files or directories to skip creation or remove existing skip markers.

  • --set, -s: backup set path.
  • --folder, -f: optional folder scope; defaults to all selected folders.
  • --file, -i: specific file to mark/unmark.
  • --dir, -d: directory path to mark/unmark recursively.

folders exclude-add / folders exclude-remove

Add or remove file exclusion rules for the selected folders.

  • --set, -s: backup set path.
  • --folder, -f: optional folder scope; defaults to all selected folders.
  • --file, -i: exact file name exclude rule to add/remove.

folders skipconvert-create / folders skipconvert-remove

Manage skip-convert markers to prevent or allow conversion attempts for specific entries.

  • --set, -s: backup set path.
  • --folder, -f: optional folder scope; defaults to all selected folders.
  • --file, -i: file name to mark/unmark for conversion skip.
  • --dir, -d: failed-conversions relative directory to mark/unmark recursively.
  • --reason, -r (create only): optional reason stored with marker.

folders examples

  • folders list: archivst -c folders list --set C:\sets\defaultset.json --verbose
  • folders add: archivst -c folders add --set C:\sets\defaultset.json --name Photos --path D:\Photos --select true
  • folders test: archivst -c folders test --set C:\sets\defaultset.json --name Photos
  • folders update: archivst -c folders update --set C:\sets\defaultset.json --name Photos --path D:\Pictures --selected true
  • folders remove: archivst -c folders remove --set C:\sets\defaultset.json --name Photos
  • folders failed: archivst -c folders failed --set C:\sets\defaultset.json --folder Photos --path 2026\02
  • folders skip-create: archivst -c folders skip-create --set C:\sets\defaultset.json --folder Photos --file image001.jpg
  • folders skip-remove: archivst -c folders skip-remove --set C:\sets\defaultset.json --folder Photos --file image001.jpg
  • folders exclude-add: archivst -c folders exclude-add --set C:\sets\defaultset.json --folder Photos --file thumb.db
  • folders exclude-remove: archivst -c folders exclude-remove --set C:\sets\defaultset.json --folder Photos --file thumb.db
  • folders skipconvert-create: archivst -c folders skipconvert-create --set C:\sets\defaultset.json --folder Photos --file bad-image.heic --reason unsupported
  • folders skipconvert-remove: archivst -c folders skipconvert-remove --set C:\sets\defaultset.json --folder Photos --file bad-image.heic

auth and login shortcut

auth login

Supports browser login flow by default, or direct token save when token + expiry are provided.

  • --token: JWT access token (for token-based login mode).
  • --expiry: token expiry in ISO8601.
  • --service: auth service name (None, Google, Aad), default None.
  • --port: optional localhost callback port (random if omitted).
  • --timeout: login wait timeout in seconds (default 180).

Example: archivst -c auth login --timeout 180

login is a top-level shortcut command that forwards to auth login. Example: archivst -c login --timeout 180

auth listen

Start a short-lived listener on a local port to complete browser-based authentication flows.

  • --port: optional local listener port.
  • --timeout: timeout in seconds.

Example: archivst -c auth listen --port 54987 --timeout 180

auth logout

No arguments. Deletes saved JWT token.

Example: archivst -c auth logout

auth status

No arguments. Shows current sign-in status and user context when available.

Example: archivst -c auth status

auth key fetch

Retrieve the scoped encryption key that matches the selected folder.

  • --folder: optional folder name to fetch scoped key data.

Example: archivst -c auth key fetch --folder Photos

auth key delete

No arguments. Deletes saved data key.

Example: archivst -c auth key delete

Utility: config, logs, help, man

config set-default-backupset (alias set-default)

Define the directory that will contain the default backup set used by future commands.

  • --dir (required): directory where defaultset.json will be stored.

Example: archivst -c config set-default-backupset --dir D:\ArchivstSets

config show

No arguments. Prints configured default directory and effective backup set path.

Example: archivst -c config show

logs

Read the CLI log files with optional filtering for headers, specific days, or error-only entries.

  • --headers: show summary header logs (run-level entries).
  • --day: day to read, format yyyy-MM-dd; defaults to today.
  • --errors: show only error console log entries.

Example: archivst -c logs --day 2026-02-24 --errors

help

No arguments. Displays quick usage and examples.

Example: archivst -c help

man

Write the CLI man page output to a file instead of printing it to the terminal.

  • --output, -o: write man page text to a file instead of stdout.

Example: archivst -c man --output archivst-manual.txt

decrypt and keys

decrypt scan

Scan for hydrated blobs within a directory so you can know what is available to decrypt.

  • --path, -p: directory to scan for hydrated blobs.
  • --only-available: show only already-downloadable files.

Example: archivst -c decrypt scan --path D:\Hydrated --only-available

decrypt run

Decrypt files using a specified key and optional password, writing the output to the desired location.

  • --path, -p: directory containing files to decrypt.
  • --key-id: key identifier to use.
  • --password: password to derive key from.
  • --out: output directory (default is in-place decryption).
  • --recursive: recurse through subdirectories.

Example: archivst -c decrypt run --path D:\Hydrated --key-id 123abc --out D:\Decrypted --recursive

keys list

No arguments. Lists locally stored decryption keys.

Example: archivst -c keys list

keys add

Store a new decryption key locally by importing or generating material.

  • --name: friendly key name.
  • --from-file: file path to import key material (base64 or hex).
  • --from-stdin: read key material from standard input.
  • --generate: generate a new random key.

Example: archivst -c keys add --name laptop --generate

keys remove

Remove a stored key when it is no longer needed or should not be used.

  • --id: key identifier to remove.

Example: archivst -c keys remove --id 123abc

keys export

Export a stored key to an encrypted file for backup or transfer.

  • --id: key identifier to export.
  • --out: output file path for encrypted export.

Example: archivst -c keys export --id 123abc --out D:\Keys\laptop.key

update

Check for updates, download releases, preview replace operations, and optionally apply updates. Sign-in is required for update operations.

  • --check: check availability only (no download/apply).
  • --apply, -a: attempt automatic apply after download.
  • --yes, -y: auto-confirm prompts.
  • --version, -v: request a specific version instead of latest.
  • --dry-run, --preview: show what would change without applying.
  • --elevated-source: internal elevated apply source path; not intended for routine user invocation.

Example: archivst -c update --check