Download and upload readings archives

A readings archive is a SQLite file with setup, synced files, and stored readings. Use it to copy history between workspaces, to keep an offline copy, or to restore local work. Run these commands in a pulled workspace. The file layout is in Archive format, and every flag is in the CLI reference.

Download the whole workspace

1. Make sure the checkout has no local changes: pnpm hmi status. Push or discard them first.

2. Run pnpm hmi download. To leave out readings or const values, add --no-readings or --no-const-values:

   pnpm hmi download
   pnpm hmi download --no-readings ./workspace.sqlite

   Without a file name, the archive goes to downloads/workspace-YYYY-MM-DD-HHmmss.sqlite.

3. Keep the file private. It can contain endpoint PIN codes.

To back up a checkout that has local changes, use the local-only form pnpm hmi download --no-readings --no-const-values <file>; see Back up and restore local changes.

Download some parameters

1. Make sure the checkout has no local changes.

2. Find the IDs of the parameters or branches you need, for example with pnpm hmi sql "SELECT id, name FROM parameter_tree_branch".

3. Run pnpm hmi download-readings with at least one --parameter or --branch. To limit the time, add --from and --to in local time. If the destination workspace does not have the same PIN endpoints, add --no-endpoints:

   pnpm hmi download-readings --branch <id> --from "2026-01-01 00:00:00" --to "2026-01-31 23:59:59"
   pnpm hmi download-readings --parameter <id> --no-endpoints ./out.sqlite

   Without a file name, the archive goes to downloads/readings-YYYY-MM-DD-HHmmss.sqlite.

Upload an archive

Uploading readings replaces stored readings in the archive’s time spans, so it needs the admin or owner role in the destination workspace. An editor can upload an archive without readings.

1. Pull the destination workspace, or open its checkout, and make sure it has no local changes.
2. To see what would change, run pnpm hmi upload <file> --dry-run.
3. Run pnpm hmi upload <file>. Answer each confirmation for setup, const, and reading conflicts. To skip the confirmations after you reviewed the dry run, add --force.
4. To make the setup equal to the archive’s, deleting entities and files the archive does not have, pull first, then run pnpm hmi upload <file> --replace.

Recover from a failed upload

• If hmi check or the push fails after the setup was written, fix the reported problem and run pnpm hmi push, or discard the changes with pnpm hmi pull --discard-local. Do not run hmi upload again until the checkout is clean.
• If writing const values or readings fails after the push, run pnpm hmi upload <file> again.
• If the push fails with pin_create_forbidden, download the archive again with download-readings --no-endpoints, or connect the device in Setup → Endpoints first.
• If upload stops after pushing because the setup changed on the server during --replace, run pnpm hmi pull, then run the upload with --replace again.