Pull a workspace

Цей контент ще не доступний вашою мовою.

A pulled workspace is a local project for developers: it keeps the workspace setup in the SQLite file setup.db and dashboard sources under src/dashboards/<id>/, and the hmi CLI syncs both with the cloud. Pull a workspace to write dashboard code with hot reload, to change setup with hmi sql and your own tools, or to follow endpoint status and Modbus traffic from a terminal.

The files of a pulled project and the local app are described in Checkout layout. How pull and push fit together is in About local sync.

Before you start

Install Node.js 22.13 or later on the 22.x line, or 23.4 or later, and pnpm, npm, or Yarn.
Make sure you have the editor, admin, or owner role in the workspace.

Get the pull command

Open the workspace in the cloud app.
Open Workspace settings → General → Develop locally. A workspace with no enabled dashboards also shows the command on its start page.
Copy the command for pnpm, npm, or yarn.

The command contains a token that works once and expires after 30 minutes. To get a new one, refresh the page.

Pull the workspace

Open a terminal in the folder where the new project folder should go.
Run the copied command before the token expires:
Terminal window
```
pnpm dlx overvis-hmi pull <token>
npx overvis-hmi pull <token>
yarn dlx overvis-hmi pull <token>
```
The command creates a workspace API key for this project, downloads the workspace, and installs the project dependencies.
Go to the project folder that the command created. It is named after the workspace.

What the command does, step by step, is in pull <token>. The key appears on the CLI keys tab of workspace settings; revoke it there to disconnect the project.

Pull without a token

If the environment already has the VITE_OVERVIS_* values (Docker, CI, or an existing .env) but no project, create the project with --scaffold:

pnpm dlx overvis-hmi pull --scaffold
# or with process environment values, which take precedence over .env:
VITE_OVERVIS_API_URL=… VITE_OVERVIS_API_KEY=… VITE_OVERVIS_WORKSPACE_ID=… \
  pnpm dlx overvis-hmi pull --scaffold

If setup.db already exists with local changes, --scaffold refuses. To throw those changes away, add --discard-local; the CLI prints what it deletes.

Open the local app

Run pnpm dev in the project folder.
Open http://localhost:8000. Use localhost, not 127.0.0.1: maps load only for the localhost origin.

The local app shows the same workspace pages as the cloud app (Workspace pages) and loads dashboards from src/dashboards/<id>/, reloading them as you edit. Changes you save in its Setup pages go straight to the cloud; run pnpm hmi pull to bring them into the project.

Work day to day

pnpm dev                 # local app at http://localhost:8000
# edit src/dashboards/<id>/…, or change setup with pnpm hmi sql "…"
pnpm hmi check           # check the local setup
pnpm hmi push            # build, check, and send your changes
pnpm hmi pull            # get cloud changes; keeps yours and records conflicts
pnpm hmi status          # local changes, conflicts, and revisions
pnpm hmi endpoint status # connection status of every endpoint
pnpm hmi endpoint traffic <endpoint-uuid> --channel rx --time 5000

If someone changed the workspace in the cloud while you worked locally, pull before you push. When pull or push reports conflicts, follow Resolve sync conflicts. The full push and pull routine, with what to do when push fails, is in Synchronize local changes.

Add dashboards and other entities

To add a dashboard:

In Setup → Dashboards, in the cloud app or the local app, select Create dashboard. Choose the Empty template for your own code, or another template to start from, and select Create.
Run pnpm hmi pull. The dashboard’s sources appear in src/dashboards/<id>/, where <id> is the new dashboard’s ID.
Edit the sources as described in Develop a dashboard locally, then run pnpm hmi push.

To add parameters, branches, endpoints, and other setup entities, create them in Setup and pull, or insert rows into setup.db with pnpm hmi sql. For a new row, get an ID with pnpm hmi id, and copy the columns of an existing row of that table. Run pnpm hmi check before you push. PIN endpoints can be connected only in Setup → Endpoints.

Change the logo locally

Create the branding/ folder if the project has none.
Add or replace branding/logo-light.svg or .png, branding/logo-dark.svg or .png, or branding/favicon.png. The open local app shows a new logo at once.
If you are an admin or owner, run pnpm hmi push to publish the files. An editor’s push of these files fails with push_admin_required.

The image rules for these files are in Branding.

Common failures

Symptom	Likely cause and fix
Pull token refused	Token expired or already used; refresh Develop locally and copy a new command
“No local workspace found”	The command ran outside the project; go to the project folder
Endpoint commands fail	The workspace’s live endpoint service is unavailable (`endpoint_live_unavailable`); try later
Dashboard blank locally	No `src/dashboards/<id>/index.tsx` and the published dashboard could not load
`client_outdated`	The server no longer supports this CLI version; run the update command it prints

Push failures are in Synchronize local changes. More recovery steps are in Troubleshooting.