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.

Note: the standalone build is a .NET 10 console app and requires the .NET 10 Desktop-independent (console) runtime to be installed. You can also run it from a portable folder without installation, as long as the app can read and write its backup set and key files.

Command and interactive mode

Archivst CLI runs a command once and exits by default (command mode), and starts an interactive shell with -i.

archivst backup --folder Photos runs once
archivst -i interactive menu

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: run backup for all folders, or one named folder.
restore: request, poll, and run a cloud restore.
folders: manage folder entries, exclusions, and skip markers in a backup set.
logs: read CLI log files with optional filtering.
auth: login, logout, status, and encryption key management.
config: set and show the default backup set directory.
decrypt: scan for and decrypt hydrated files.
keys: manage locally stored decryption keys.
copy: copy status / copy cancel — show or stop the background copy job run by the Archivst Windows service.
update: check for and apply CLI updates (sign-in required).
help: quick usage and examples.
man: write the CLI man page to a file.
login: shortcut for auth login.

Commands that support backup set input use --set -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).
--no-filedetail-cache: do not use the file detail cache files to determine unchanged or already-backed-up files.

Example: archivst 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 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 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.
--no-filedetail-cache: do not use the file detail cache files during restore decisions.

Example: archivst 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.

Example: archivst folders list --verbose

Folders add

Add a new folder entry to the backup set with its local path and selection state, or describe the folder in a JSON object (or a JSON file).

--set, -s: backup set path.
--name: folder display name to add.
--path: local folder path.
--select: selected flag (default true).
--json: a JSON object defining the folder, or the path to a JSON file containing it. --name/--path override the JSON values when both are supplied.

JSON shape: an object (or a single-element array) describing one folder. FolderName and Path are required; any other folder member may be set.

Example (name/path): archivst folders add --name Photos --path D:\Photos --select true

Example (JSON file): archivst folders add --json C:\sets\newfolder.json

Example (inline JSON): archivst folders add --json {"FolderName": "Photos", "Path": "D:\Photos", "Selected": true, "Frequency": "Daily", "CompressImages": 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.

Example: archivst folders test --name Photos

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

Example: archivst folders update --name Photos --path D:\Pictures --selected true

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.

Example: archivst folders remove --name Photos

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.

Example: archivst folders failed --folder Photos --path 2026\02

Folders skip-create / Folders skip-remove

Mark specific files or directories to skip creation or remove existing skip markers. skip-create writes a per-file .skipverify marker (recursive with --dir) so the backup skips copying that content to the destination; skip-remove deletes the marker to un-skip a file or directory and include it in backups again.

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

Example (create): archivst folders skip-create --folder Photos --file image001.jpg

Example (remove): archivst folders skip-remove --folder Photos --file image001.jpg

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.

Example (add): archivst folders exclude-add --folder Photos --file thumb.db

Example (remove): archivst folders exclude-remove --folder Photos --file thumb.db

Folders skipconvert-create / Folders skipconvert-remove

Manage skip-convert markers to prevent or allow conversion attempts for specific entries. Archivst converts certain file types (such as images) before saving, and failed conversions can be listed with folders failed. skipconvert-create writes a .skipconvert marker so those entries are copied as-is without a conversion attempt; skipconvert-remove deletes the marker to re-enable conversion.

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

Example (create): archivst folders skipconvert-create --folder Photos --file bad-image.heic --reason unsupported

Example (remove): archivst folders skipconvert-remove --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 auth login --timeout 180

login is a top-level shortcut command that forwards to auth login. Example: archivst 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 auth listen --port 54987 --timeout 180

Auth logout

No arguments. Deletes saved JWT token.

Example: archivst auth logout

Auth status

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

Example: archivst 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 auth key fetch --folder Photos

Auth key delete

No arguments. Deletes saved data key.

Example: archivst 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 config set-default-backupset --dir D:\ArchivstSets

Config show

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

Example: archivst 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 logs --day 2026-02-24 --errors

Help

No arguments. Displays quick usage and examples.

Example: archivst 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 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 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 decrypt run --path D:\Hydrated --key-id 123abc --out D:\Decrypted --recursive

Keys list

No arguments. Lists locally stored decryption keys.

Example: archivst 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 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 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 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 update --check

Copy

Inspect and control the backup copy that the Archivst Windows service runs in the background. Use this when a scheduled copy (started through a desktop app or a prior CLI trigger) is running on this machine and you want to monitor or stop it from the terminal.

Copy status

Reports whether the service is copying a folder right now, and which one. No arguments.

Example: archivst copy status

Copy cancel

Requests that the service cancel the active copy. No arguments. The service applies the cancellation on its next check, so allow a short pause before re-checking with copy status.

Example: archivst copy cancel

Troubleshooting

Network errors

Confirm you have an internet connection and that the Archivst endpoints are reachable from this machine (check any proxy or corporate firewall). If the app settings are not where you expect, look for a local appsettings.json next to the .exe first, then %APPDATA%\ArchivstDesktop\appsettings.json for the roaming copy, and confirm the API domain configured there is correct.

Authentication fails

JWT tokens are time sensitive, so first check that your system clock is correct. Then sign out and back in with archivst auth logout followed by archivst auth login, and confirm the sign-in succeeded with archivst auth status.

Permission denied uploading to blob storage

Your Archivst account must have an active storage allocation; contact Support if the account is new or recently downgraded. Make sure the folder you are backing up maps to a valid destination (Cloud, Local, or FTP) and that you are signed in — cloud uploads require an authenticated token. For FTP folders, re-enter the password when prompted with --ftp-pass.

Build from source

Archivst.CLI is a standard .NET 10 console project under Archivst.CLI in the repository. Build it the same way as any .NET project:

dotnet build
# or produce a publishable folder
# dotnet publish -c Release

The published output can be copied to any machine with the .NET 10 runtime installed and run directly — no installer required.