HMI CLI reference

@overvis/hmi-cli provides the hmi command for developers who work on a workspace on their own computer. It downloads the workspace setup and files into a local project, sends local changes back, builds dashboards, and follows endpoints and checkpoints from a terminal.

Run it from a pulled project as pnpm hmi <command> …. Outside a pulled project, run it as npx overvis-hmi (or pnpm dlx overvis-hmi): the overvis-hmi package runs the hmi command of @overvis/hmi-cli at the same version. Each command runs once and exits; endpoint status --watch and endpoint traffic keep running until Ctrl-C or --time.

The CLI needs Node.js 22.13 or later on the 22.x line, or 23.4 or later.

Related: Pull a workspace, Synchronize local changes, Resolve sync conflicts, About local sync.

Usage summary

hmi pull <token> [--api <url>]
hmi pull [--discard-local] [--rebuild] [--scaffold] [--api <url>]
hmi push [--dry-run] [--api <url>]
hmi build [dashboardId...]
hmi resolve (<type> <id> | file <path> | --all) (--ours | --theirs)
hmi status [--api <url>]
hmi check
hmi sql "<stmt>" [--json]
hmi export [--local] [file]
hmi import <file> [--override <type:id>...]
hmi download [--no-readings] [--no-const-values] [file]
hmi download-readings [--parameter <id>...] [--branch <id>...] [--from <date-time>] [--to <date-time>] [--no-endpoints] [file]
hmi upload <file> [--replace] [--dry-run] [--force]
hmi id [count]
hmi endpoint status [--watch] [--json] [--time <ms>] [--api <url>]
hmi endpoint traffic <endpointId> [--channel <name>...] [--json] [--time <ms>] [--api <url>]
hmi checkpoint list [--all] [--json] [--api <url>]
hmi checkpoint create <name> [--reason <text>] [--json] [--api <url>]
hmi checkpoint rename <checkpointId> <name> [--json] [--api <url>]
hmi checkpoint delete <checkpointId> [--json] [--api <url>]
hmi checkpoint changes <checkpointId> [--all] [--json] [--api <url>]
hmi checkpoint revert (<checkpointId> | --at <date-time>) [--dry-run] [--json] [--api <url>]
hmi --version

Each command accepts only the flags shown on its line. -v or --version prints the CLI version. -h or --help prints help; endpoint, checkpoint, and id also have their own help. --api <url> uses another API base URL for one command without changing .env.

Finding the project

Commands other than pull <token>, build, and id work on a pulled project. They take the VITE_OVERVIS_API_URL, VITE_OVERVIS_API_KEY, and VITE_OVERVIS_WORKSPACE_ID values from the process environment when they are set, and otherwise from the nearest .env in the current folder or a parent folder. endpoint, checkpoint, and pull --scaffold need only these three values. The other commands also need the project’s setup.db.

Checkout layout

A pulled project is a Vite app. pull <token> creates it in the current directory, in a folder named after the workspace in lowercase ASCII words joined by hyphens, with (1), (2), and so on added when that folder already exists.

Files

Path	Content
.env	API URL, workspace API key, and workspace ID (.env)
setup.db	Local copy of the workspace setup, with local changes and conflicts (tables)
package.json	Dependencies and commands of the project; pnpm build runs hmi build
src/dashboards/<id>/	Source of each dashboard, in a folder named by the dashboard ID
dist/dashboards/<id>/	Built dashboards, written by hmi build and sent by push
src/lib/	Optional shared modules for your dashboards
edge/<endpointId>/<NAME>.TXT	Sources of MC252 edge programs, one per program
branding/	Workspace logos and favicon (Branding files)
AGENTS.md, README.md	Notes for people and coding assistants. Pull adds a starting AGENTS.md when it is missing
downloads/	Default destination of download and download-readings

Which files sync

Synced with the workspace: src/dashboards/<id>/, src/lib/, edge/, branding/, package.json (merged; see below), pnpm-lock.yaml, AGENTS.md, README.md, and any other file you add to the project.

Rewritten by every pull and never synced: vite.config.ts, tsconfig.json, index.html, src/main.tsx, src/styles.css, .gitignore, pnpm-workspace.yaml, templates/README.md, and templates/schemas/. Files under scripts/ and templates/dashboards/ are not synced either. Do not keep your own changes in these files.

Never synced: node_modules/, .env, .env.local, .git/, .hmi/, downloads/, dist/ (push sends the built dashboards it needs), src/dashboard-externals/, setup.db, and operating system files such as .DS_Store, Thumbs.db, and desktop.ini.

Pull updates the versions of the HMI packages and the libraries the project template provides in package.json, and keeps the dependencies you added.

setup.db

setup.db is a SQLite database with one table per kind of setup item. Read and change it with hmi sql.

Table	Content
workspace	The workspace: name, time zone, location, and automation limits
dashboard	Dashboards
endpoint	Endpoints
edge_program	MC252 edge programs
parameter_tree_branch	Branches of the parameter tree
parameter	Parameters
report_preset	Reports
report_comment	Report comments
alarm_rule	Alarm rules
automation	Automations
entity_conflict	Server versions of setup items in conflict
file_conflict	Server versions of files in conflict
local_tombstone	Items you deleted locally that push will delete on the server
file_state, meta	Sync bookkeeping. Do not change these tables

Each setting is its own column. Names, descriptions, and other translatable texts, and structured values such as a parameter’s source and value_type, are JSON text in their column. Nullable columns accept SQL NULL for absent metadata; non-null values must be valid JSON. Their shapes match the setup types of @overvis/hmi-shared. Every ID is a UUID; get new ones with hmi id. To see a table’s columns, run pnpm hmi sql "SELECT sql FROM sqlite_master WHERE name = '<table>'".

Pull also stores the workspace’s automation limits, which hmi check checks automations against. They are read-only locally: push does not send them, and only admins and owners change them in workspace settings.

The scaffolded .gitignore does not ignore setup.db. If you commit it to Git, a fresh clone holds your unpushed changes and the revision of your last pull.

After a CLI update, the CLI upgrades an older setup.db when it opens it; you do not need to pull again. Some upgrades make the next pull download the whole setup; your local changes stay, and push waits until that pull. A setup.db written by a newer CLI is refused until you update the HMI packages. A setup.db too old to upgrade opens only for hmi export --local and hmi pull --rebuild.

Branding files

The logo and favicon files are branding/logo-light.svg or .png, branding/logo-dark.svg or .png, and branding/favicon.png. Their image rules are in Branding. Other files under branding/ are ordinary synced files. Pull does not create an empty branding/ folder.

Pull and push keep the file bytes as they are: unlike uploads in workspace settings, they do not resize images. hmi check and push reject invalid logo images, PNG logos larger than 4096 pixels per side or 4 million pixels in total, other extensions on these names, and two formats for one theme. Only admins and owners can push changes to these files (push_admin_required).

The local app shows the logos from disk, including unpushed changes, and updates when you add, replace, or delete one.

.env

Pull writes .env:

VITE_OVERVIS_API_URL=…
VITE_OVERVIS_API_KEY=…
VITE_OVERVIS_WORKSPACE_ID=…

Key	Value
VITE_OVERVIS_API_URL	API base URL
VITE_OVERVIS_API_KEY	The workspace API key that pull <token> created
VITE_OVERVIS_WORKSPACE_ID	Workspace ID

Values in the process environment take precedence over .env for every command except pull <token>. The scaffolded .gitignore ignores .env and .env.local. The API URL must be reachable from your computer.

Local app (pnpm dev)

pnpm dev serves the local workspace app at http://localhost:8000. It listens on 127.0.0.1:8000, which SSH port forwarding can reach. Open it as localhost: maps load only for the http://localhost:8000 origin, not for http://127.0.0.1:8000.

The local app shows the same workspace pages as the cloud app and works with the same workspace through the workspace API key; see Workspace pages. Changes you make in its Setup pages are saved in the cloud at once, like in the cloud app; run hmi pull to bring them into setup.db.

A dashboard loads from src/dashboards/<id>/index.tsx and reloads as you edit it. Without that file, the app loads the published dashboard and shows a warning. The app shows each dashboard’s unpushed configuration in setup.db, such as an edited drawing, in place of the saved one; edits made after the dashboard opened show after a reload. The local app runs only under pnpm dev: pnpm build builds the dashboards for push, not the app. Host props and routing are in @overvis/hmi-workspace-ui.

pull <token>

Create a new local project from a pull token. Editors, admins, and owners copy the command with the token from Workspace settings → General → Develop locally. A token works once and expires after 30 minutes. An invalid, expired, or used token fails with a hint to copy a new command. A refused pull, for example without editor access, leaves the token unused.

pnpm dlx overvis-hmi pull <token>
pnpm dlx overvis-hmi pull <token> --api https://api.example.com

The token carries the API URL; --api overrides it. The command:

1. Creates a workspace API key, named after your computer’s host name.
2. Creates the project folder, writes the project files and .env, and creates setup.db.
3. Downloads the workspace setup and synced files.
4. Installs the project dependencies.
5. Adds AGENTS.md when the workspace has none.
6. Uploads the files the pull itself created or merged, such as package.json and AGENTS.md, so the workspace and the project match.

It does not build dashboards; push does. --discard-local, --rebuild, and --scaffold are errors with a token.

The workspace API key works only for this workspace and cannot create pull tokens. Each token creates a new key and leaves earlier keys working. To disconnect a project, revoke its key on the CLI keys tab of workspace settings, where editors see their own keys and admins and owners see everyone’s, or under Local workspace keys in your account’s API keys settings.

pull (tokenless)

Download what changed in the workspace since the last pull, keeping your local changes. Local changes are setup items you added, changed, or deleted, and synced files you added, changed, or deleted.

• Items and files you did not change take the server version. Items and files deleted on the server are deleted locally.
• Items and files you changed keep your version. When the server also changed or deleted them differently, pull records the server version as a conflict. The same change on both sides is not a conflict.
• An item you deleted locally that the server changed is a conflict; your deletion stays. An item the server deleted that other local items still refer to is kept and recorded as a conflict.
• The workspace name has no conflicts: a local rename stays until you push it.
• Quick reports that were never saved stay in the cloud. Once saved, the next pull brings them.

Pull downloads only file contents that no local file already has, so unchanged, moved, and copied files are not downloaded again. After applying the changes, pull uploads the files the pull itself created or merged, such as package.json. Your own kept edits are not uploaded; hmi push sends them. Pull ends by printing how many conflicts exist.

pnpm hmi pull
pnpm hmi pull --discard-local
pnpm hmi pull --rebuild
pnpm hmi pull --scaffold

Flag	Meaning
--discard-local	Download the whole workspace again. Prints, then deletes, all local changes and conflicts, and resets your package.json edits to the workspace’s version
--rebuild	Recreate setup.db and download the whole workspace setup, for a setup.db too old to upgrade. Refuses with local changes unless you add --discard-local
--scaffold	Create the project from the VITE_OVERVIS_* values in the environment or .env, without a token. Refuses with local changes unless you add --discard-local
--api	Use another API base URL

--scaffold is for places that already have the three values but no project, such as Docker, CI, or a folder with only .env. A pull without flags never refuses because of local changes. How pull and push fit together: About local sync.

push

Send local changes to the workspace. Push builds the dashboards, runs hmi check, uploads the file contents the workspace does not have yet, and then applies all changes at once.

pnpm hmi push
pnpm hmi push --dry-run
pnpm hmi push --api https://api.example.com

Flag	Effect
--dry-run	Print what push would send as JSON and send nothing. Works with unresolved conflicts
--api	Use another API base URL

The --dry-run JSON on stdout lists the setup changes, the changed file paths, and file counts. Messages go to stderr, so scripts can read stdout as JSON. Push has no --force option.

With nothing to push, push prints Nothing to push. and does not contact the server. It refuses while conflicts from a pull are unresolved (Refusing push: N unresolved conflict(s) …). It also refuses changed files under src/dashboards/<id> when setup.db has no dashboard <id>, for example one created, copied, or deleted in the cloud after your last pull.

Push sends every kind of setup item: dashboards, endpoints, MC252 edge programs, branches, parameters, reports, report comments, alarm rules, and automations, with the workspace name, time zone, and location. An edge program and its source file under edge/ must change together; MC252 edge programs lists what push rejects. Either the whole push is applied or nothing is.

The server checks the setup the push leaves with the same rules as the Setup pages: formulas must evaluate, Modbus addresses must cover the bytes a value type needs, and the branches, endpoints, and calculation inputs a parameter refers to must exist, without loops. Problems already on the server do not block unrelated changes, but every item the push changes must pass. Automations and alarm rules are checked against the setup the push leaves; see Automations and alarm rules. A new WireGuard endpoint gets its VPN address a few seconds after the push.

Report comments can only be added or deleted. Deleting one locally deletes it on the server whoever wrote it, as editors can in the app. A new comment must have you as its author.

Before a push that changes the setup, the server takes an automatic checkpoint of the setup as it was, with the push command as its reason; see checkpoint.

Limits:

• Each file can be at most 50 MiB.
• The setup changes and file list of one push can be at most 64 MiB in total. A push larger than 3 MiB, for example after hmi upload of a large archive, is sent in parts automatically, and the CLI prints Uploading the changes in N parts…. Sending in parts does not raise the 64 MiB limit: a larger push fails with push_stage_too_large and changes nothing.

If push gets no answer, for example because the network dropped, hmi status shows unfinished push: <id> and the next hmi push retries it safely; see Retry an interrupted push.

Push errors

A failed push prints push failed: <code> and then a JSON object with details, such as the item ID, file path, or reason, on stderr. The code and details stay the same between versions; the English message can change. Nothing is applied.

Code	Meaning and what to do
push_conflict	Items or files you changed were changed or deleted on the server since your last pull. details.conflicts lists items as { type, id, serverRevision } (null means deleted) and details.files lists paths. Pull, resolve, and push again
push_admin_required	Renaming the workspace and changing its logo or favicon need an admin or owner. details.entityType is workspace for the name; details.files lists the files. Put them back as on the server, or ask an admin to push them
push_validation_failed	The setup breaks a rule. details.reason, such as missing_endpoint or calc_cycle, names the rule and details.entityId the item. A comment by someone other than you fails with reason: "author_not_pusher"
pin_create_forbidden	Push cannot create a PIN endpoint. Connect PIN devices in Setup → Endpoints
pin_identity_frozen	Push cannot change a PIN endpoint’s kind, PIN, public key, SKU, protocol, or device details
push_stage_too_large	The push is over the 64 MiB limit. Push the changes in smaller batches
push_id_reused	The ID of an interrupted push cannot be reused; see Retry an interrupted push
hmi check failed	hmi check found errors; they are printed after the code

Other codes name the item or path in their details.

build

Build dashboards from source without contacting the server. hmi push runs the same build through the project’s build script.

pnpm hmi build
pnpm hmi build 3f0c3c5e-4a53-4d3f-9a4e-7f8d9d2b1c10

Argument	Meaning
(none)	Build every src/dashboards/<id> and delete dist/dashboards/<id> folders whose source no longer exists
dashboardId...	Build only these dashboards; an ID without src/dashboards/<id> is an error

The project root is the nearest folder with a package.json, starting from the current folder. For each dashboard with an index.tsx, index.ts, index.jsx, or index.js entry, the build type-checks the entry, the files it imports, and the shared src/symbols against the host contract, then writes dist/dashboards/<id>/:

File	Content
index.js	ES module bundle; the host’s shared modules stay imports that the host provides
index.css	Tailwind utilities the dashboard uses, scoped to the dashboard container
config.schema.json	JSON Schema of dashboardConfigType (also written to the source folder)
assets/	Copy of the source assets/ folder, when present
hmi-dashboard.json	Build manifest: abi (host contract version), builder (CLI version), and the supportedLocales and pages of manifest.ts when the dashboard has one

A dashboard whose sources and build tools have not changed reuses its previous build, kept in .hmi/dashboard-builds.

An optional manifest.ts beside the entry declares supportedLocales (required) and pages (tab order, each a path and a localized name, / first). It may contain only type imports, type declarations, and const declarations of literal values, and the entry must re-export both from ./manifest.ts.

A dashboard folder without an entry is skipped with a warning. The build uses Vite, @vitejs/plugin-react, @tailwindcss/vite, Tailwind CSS, and TypeScript from the project; pulled projects list them as development dependencies. A project that lacks them fails with an error that asks you to install the dependencies. The type check needs TypeScript 7.0.x; otherwise hmi build stops with an error that names the installed version.

A published dashboard without a manifest, or with one built for another host contract version, shows “Dashboard needs a rebuild” instead of the dashboard. Build it with the current CLI and push.

resolve

Settle conflicts recorded by hmi pull. Give exactly one of --ours or --theirs.

pnpm hmi resolve parameter <id> --ours
pnpm hmi resolve file src/dashboards/<id>/index.tsx --theirs
pnpm hmi resolve --all --theirs

Argument / flag	Meaning
<type> <id>	One item: dashboard, endpoint, edge_program, parameter_tree_branch, parameter, report_preset, report_comment, alarm_rule, automation
file <path>	One synced file
--all	Every conflict, the same way
--ours	Keep the local version (or local deletion); the next push replaces the server version. An item the server deleted is created again by that push
--theirs	Replace the local version with the server’s, or delete it locally when the server deleted it. For files, the server content is written to disk

Taking the server’s deletion of an item that other local items still refer to fails with a hint to resolve those first or use --all. See Resolve sync conflicts.

status

Show local changes, conflicts, and revisions:

• the number of local changes by kind of item, and the changed files;
• the revision of your last pull and the server’s current setup revision (unavailable when the server cannot be reached);
• conflicts: N, with one line per conflict, such as parameter <id> (changed on server) or file <path> (deleted on server);
• unfinished push: <id> when the outcome of a push is unknown.

pnpm hmi status
pnpm hmi status --api https://api.example.com

check

Check setup.db and the synced files without contacting the server:

• every setup item against its schema;
• parameters: formulas, Modbus address sizes, branch loops, missing endpoints, and calculation inputs and loops (duplicate names are allowed);
• reports: their layout and Sankey flows;
• MC252 edge programs against their files under edge/ (MC252 edge programs);
• automations and alarm rules against the local parameters, endpoints, workspace location, and the workspace’s automation limits (Automations and alarm rules);
• branding files and report comment authors.

Errors print the same code and details as hmi push; automation errors add one line per problem. Warnings, such as edge program validator findings, do not fail the check. Recipients of the members kind are checked by the server on push. An automation already on the server that is over limits an admin lowered later is only a warning: you can leave it, disable it, or move it, but not change it otherwise. A new automation must be within the limits.

pnpm hmi check

Push runs the same check and stops with push failed: hmi check failed when it fails.

sql "<stmt>"

Run SQL against setup.db. One command runs as one transaction: several statements separated by ; are allowed, and an error in any of them rolls back all of them. Changes you make are local changes until you push them; deleting an item that was already pushed makes push delete it on the server.

pnpm hmi sql "SELECT id, name FROM dashboard"
pnpm hmi sql "UPDATE parameter SET units = '\"°C\"' WHERE id = '…'" --json

Flag	Effect
--json	Print { rows, changes, truncated, totalRows } as JSON

rows holds the result of the last statement, including RETURNING rows. changes counts the rows the statements inserted, updated, or deleted themselves, not rows deleted along with them. --json prints at most 500 rows (truncated is then true) and 200,000 characters; above that it prints an error with changes and rowCount, and the changes stay saved.

hmi sql allows intermediate states that hmi check would reject, so you can change several rows step by step. Run hmi check when you are done.

export / import

Save local changes to a JSON file and apply them again later. export writes only your unpushed changes, with the revision of your last pull as baseRevision.

pnpm hmi export > mine.json
pnpm hmi export --local > raw.json
pnpm hmi import mine.json

Flag / arg	Meaning
[file]	Write the export to this file instead of stdout
--local	Dump every local table as it is, also from a setup.db too old to upgrade. For inspection only; import does not accept it
import <file>	Apply the additions, changes, and deletions in the file. Refuses items changed on the server after baseRevision and reports with invalid settings (recipe_invalid)
--override	Import this item even if it was changed after baseRevision, as type:id; repeat for each item

import checks the whole file first: unknown fields, malformed deletions, or an item that fails its schema change nothing. A deletion that would also delete an item the import keeps, such as the dashboard of an automation or a parent branch, is refused too. The next push sends the imported changes.

To restore local work onto a fresh copy of the workspace, use download, pull --discard-local, and upload; see Back up and restore local changes.

download

Write a SQLite archive of the whole workspace: the setup and synced files from the local project, and the stored readings and constant values of all parameters from the cloud.

pnpm hmi download
pnpm hmi download --no-readings ./workspace.sqlite
pnpm hmi download --no-readings --no-const-values ./local-backup.sqlite

Flag	Meaning
--no-readings	Leave out stored readings
--no-const-values	Leave out stored constant parameter values

download needs a project without local changes, unless you give both --no-readings and --no-const-values. That form contacts no server and is the way to back up a project with local changes: it holds the whole local setup, including new, changed, and deleted items and files. The check for local changes does not check whether the project has the latest cloud changes.

Without a file name, the archive goes to downloads/workspace-YYYY-MM-DD-HHmmss.sqlite in local time. An existing file is not overwritten. downloads/ is not synced.

Archives can contain endpoint PIN codes. The CLI makes them readable only by you. A failed download leaves no file at the destination. The file format is in Archive format.

download-readings

Write a SQLite archive of selected parameters with the branches they need, their endpoints, and their stored readings. Constant values are not included. It needs a project without local changes.

pnpm hmi download-readings --parameter <id>
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

Flag	Meaning
--parameter	Include this parameter (repeatable)
--branch	Include this branch, its sub-branches, and their parameters (repeatable)
--from / --to	Local time window YYYY-MM-DD HH:mm:ss; --to includes that whole second
--no-endpoints	Leave out endpoints

Give at least one --parameter or --branch; unknown IDs fail. --branch does not add parent branches or calculation inputs. Without --from and --to, all history is included. Without a file name, the archive goes to downloads/readings-YYYY-MM-DD-HHmmss.sqlite. An existing file is not overwritten.

upload <file>

Merge an archive into this workspace:

1. Writes the archive’s setup and files into the project as local changes. Files with the same bytes as on disk are not conflicts.
2. Pushes them.
3. Writes the archive’s constant values. Values only in the workspace stay.
4. Replaces stored readings: for each parameter, the readings between the first and the last time in the archive are replaced by the archive’s. Report and chart history over those times is recalculated.

pnpm hmi upload ./out.sqlite --dry-run
pnpm hmi upload ./out.sqlite
pnpm hmi upload ./out.sqlite --replace

Flag	Effect
--replace	Also delete the setup items and synced files the archive does not have, so the setup equals the archive’s. Constant values not in it stay
--dry-run	List the setup, constant value, and reading changes the upload would make, and change nothing
--force	Skip the confirmations

The archive goes into the workspace of the project; the archive does not name one. Upload refuses a project with local changes, also with --force. In a terminal it asks before each setup difference, new or changed constant value, and time span that already has readings (default no); without a terminal, any such conflict fails. With --replace, upload refuses a project behind the server’s setup, and if the setup changes on the server meanwhile, it fails after pushing and asks you to pull and replace again.

An archive with readings needs the admin or owner role, because it replaces readings; editors can upload archives without readings. Renaming the workspace or changing its logo or favicon also needs an admin or owner. Push cannot create a PIN endpoint the workspace does not have, so such an archive fails unless it was made with download-readings --no-endpoints or the device is already connected in Setup → Endpoints. Constant value keys must be 1–200 characters and values at most 1024 bytes.

If the push fails, the setup stays as local changes: fix the problem and run hmi push, or run hmi pull --discard-local. If writing constant values or readings fails after the push, run hmi upload again. When the server is busy with other readings imports, upload waits and retries every second; Ctrl+C stops it. Recovery steps are in Download and upload readings archives.

id

Print new UUIDs, one per line, for new setup items and dashboard folders. Without a count it prints one.

pnpm hmi id
pnpm hmi id 5

Setup item IDs are always UUIDs, never names or sequential numbers.

endpoint status

Print the connection status of every endpoint in the workspace: name, state (connecting, connected, disconnected, error, or unknown before the first report), the address in use, and when it connected or its last error.

pnpm hmi endpoint status
pnpm hmi endpoint status --json
pnpm hmi endpoint status --watch
pnpm hmi endpoint status --watch --json --time 60000

Flag	Meaning
--watch	Print the statuses, then one line per change until Ctrl-C
--json	Print JSON; with --watch, one JSON object per line
--time <ms>	With --watch: stop after this many milliseconds
--api	Use another API base URL

With --watch --json, the first line is a snapshot event, then each change is a change event with endpointId and status. The output matches the endpoint.status and endpoint.watchStatus API procedures.

endpoint traffic <endpointId>

Follow the live Modbus traffic of one endpoint until Ctrl-C or --time. There is no history: frames start when the command connects.

pnpm hmi endpoint traffic <endpoint-uuid>
pnpm hmi endpoint traffic <endpoint-uuid> --channel sent --channel rx
pnpm hmi endpoint traffic <endpoint-uuid> --channel events --json --time 5000

Channel	What you see
tx	Requests to the device as Modbus RTU without CRC (unit + PDU)
sent	Full Modbus TCP ADUs written to the device
rx	Full Modbus TCP ADUs received from the device
events	Connection changes and request errors, with a machine-readable reason

Flag	Meaning
--channel <name>	Only these channels (repeatable); all four when omitted
--json	One frame per line as JSON
--time <ms>	Stop after this many milliseconds
--api	Use another API base URL

Text lines show the local time, the channel, the bytes as hex, and the request id when the requester set one; the same id marks the matching sent and rx frames and request errors. JSON frames carry data as lowercase hex, id, and, on sent, write (shared by frames sent in one TCP write). Parameter values are not part of this output.

checkpoint

Work with the workspace’s setup checkpoints. A checkpoint marks the setup at one moment: people and the assistant take named ones, and the system takes automatic ones before pushes and other large changes. The same checkpoints appear in Setup → Activity history. Checkpoints need the editor, admin, or owner role. These commands work on the server’s setup; they do not read or change setup.db.

pnpm hmi checkpoint list
pnpm hmi checkpoint list --all --json
pnpm hmi checkpoint create "Before rewiring" --reason "Relay moves to channel 2"
pnpm hmi checkpoint rename <checkpoint-uuid> "After rewiring"
pnpm hmi checkpoint delete <checkpoint-uuid>
pnpm hmi checkpoint changes <checkpoint-uuid>
pnpm hmi checkpoint revert <checkpoint-uuid> --dry-run
pnpm hmi checkpoint revert --at "2026-10-09 14:30:00"

Subcommand	What it does
list	One line per checkpoint, newest first: ID, local time, name or kind, author, reason
create <name>	Take a named checkpoint of the server’s current setup; unpushed local changes are not in it
rename <id> <name>	Rename a named checkpoint
delete <id>	Delete a named checkpoint; the setup and the activity history do not change
changes <id>	Setup items created, changed, and deleted after the checkpoint, up to the next listed checkpoint or the current setup
revert <id>	Return the server setup to the checkpoint as a new revision, after a Before revert checkpoint that undoes it
revert --at <time>	Return the server setup to how it was at a local YYYY-MM-DD HH:mm:ss, including changes saved during that second

Flag	Meaning
--all	list: every kind, including daily and before bulk delete. changes: stop at the next checkpoint of any kind
--reason <text>	create: why the checkpoint is taken (up to 500 characters)
--at <time>	revert: the moment to revert to instead of a checkpoint
--dry-run	revert: list what the revert would change, and change nothing
--json	Print the result as JSON
--api	Use another API base URL

Without --all, list shows named checkpoints and the automatic ones taken before a push, before assistant changes, before a template, before an import, and before a revert. Automatic checkpoints cannot be renamed or deleted; they expire after 30 days. Names are 1–120 characters.

revert prints the setup items and files it creates, changes, and deletes, the constant values it restores (from the checkpoint, or for --at from the nearest earlier one), and deleted MC252 devices it recreates. It asks you to confirm each such device on site: press R on the device, or type the code from its screen and press Enter. Without a terminal, or with --json, it fails with checkpoint_revert_device_unconfirmed and names the devices. It fails with checkpoint_revert_conflict when the setup changes between its preview and the revert, and with checkpoint_revert_unreadable when items of the checkpoint can no longer be read. The next hmi pull brings the reverted setup; local edits made before the revert become conflicts. See Revert the setup to a checkpoint.

Versions and updates

The HMI packages are in beta: their versions are 0.x, and a new minor version (0.1 to 0.2) may change commands, project files, or package exports incompatibly. A pulled project depends on @overvis/hmi-cli, @overvis/hmi-shared, and @overvis/hmi-workspace-ui at one shared version, which overvis-hmi also has. Keep the three on the same version. pnpm hmi --version prints the installed one.

Update a project by updating the three packages together:

pnpm add @overvis/hmi-cli@latest @overvis/hmi-shared@latest @overvis/hmi-workspace-ui@latest

With npm, run npm install with the same packages; with Yarn, yarn add. The next pnpm hmi push sends the changed package.json and rebuilds the dashboards with the new version.

The API refuses a CLI or local workspace app older than the version it supports with client_outdated; the CLI then prints the version it needs and this update command. A newer version that is still supported keeps working. A dashboard built with older tools shows Dashboard needs a rebuild until you update and push.

Exit status and errors

A command that fails prints the error to stderr, for most commands as <command> failed: <message>, and exits with a non-zero status. This includes a push with conflicts.

Message	Cause and fix
No local workspace found…	No .env values or setup.db here or in a parent folder. Run the command in the project, or create it with pull --scaffold
No pulled workspace found…	endpoint or checkpoint found no .env values
Found .env … but setup.db is missing	Run hmi pull --scaffold or a new token pull
setup.db newer than the CLI (“Update the CLI”)	Update the HMI packages in the project
setup.db too old to upgrade	hmi export --local > <file> to keep a copy, then hmi pull --rebuild
the server needs @overvis/hmi-cli version <minimum> or newer (client_outdated)	The server no longer supports this CLI version. Run the update command printed after it

A CLI that is older than the server but still supported keeps working: it ignores new fields in the server’s answers. More recovery steps are in Troubleshooting.

See also

• About local sync
• Synchronize local changes and Resolve sync conflicts
• @overvis/hmi-shared and @overvis/hmi-workspace-ui