Updating devices with pvr

pvr is the Pantavisor repo tool: a git-like CLI that checks a device's state out to your machine as plain files, lets you edit it (including adding whole apps from Docker images), and posts the result back as a new revision on the device's trail. It is the command-line counterpart of everything the device tabs do in the UI — same trail, same revisions.

This page covers the two workflows the Hub UI meets in the middle:

• Clone → edit → post: update a device entirely from the command line.
• Export a part with pvr export and upload it in the device's Manage tab — useful to move a container from one device to another, or to hand a tested part to someone who only uses the UI.

The pvr workflow

0. Log in once

pvr login

pvr talks to https://api.pantahub.com by default; when self-hosting, point it at your API with -b <baseurl> (or PVR_BASEURL).

1. Clone the device

pvr clone <user-nick>/<device-nick> my-device
cd my-device

You get the device's current state as a directory tree — the same tree the Files tab shows: the BSP, one directory per container, and their configuration. pvr keeps a pristine copy, so pvr status and pvr diff work like their git namesakes.

2. Change something

Edit files directly, or manage whole applications:

# add a container from a Docker image
pvr app add --from=nginx:latest my-nginx

# later: refresh it to the current image
pvr app update my-nginx

# inspect what changed
pvr status
pvr diff

3. Commit and post

pvr add .
pvr commit -m "add nginx container"
pvr post -m "add nginx container"

pvr post uploads any new objects and appends the state as the next revision on the device's trail. From here it is a normal update: the device picks the step up when online, and you can watch it in the Releases tab (or with pvr logs <device>).

put vs post

pvr put overwrites a target repository in place; pvr post appends a new revision to a device's trail. For updating devices you almost always want post.

Exporting a part for the Manage tab

The Manage tab of a device shows its state split into parts — the BSP and each container — and works with exactly the tarball format pvr export produces (a json state patch plus the referenced objects/).

Create the export with pvr

From a checkout of the source device (or any pvr repo):

# everything
pvr export my-device.tgz

# just one or two parts — e.g. a single container
pvr export --parts my-nginx my-nginx.tgz

--parts takes a comma-separated list; leaving it out exports the whole state. (The Manage tab's Export device / Export selected parts buttons produce the same kind of tarball from the UI, and pvr import unpacks one into a local repo.)

Upload it on the target device

In the target device's Manage tab:

1. Begin Transaction — snapshots the current state so you edit a copy.
2. Upload the tarball as a new part (drag & drop). Its state is merged into the transaction and its objects are queued; you can also remove existing parts here.
3. Review the transaction diff — a side-by-side of the current state versus what you are about to deploy.
4. Commit Transaction with a commit message. The Hub uploads the new objects and appends the merged state as the next revision; the device walks to it like any other update.

Until you commit, nothing touches the trail — cancelling the transaction (or leaving the page) discards the changes.

Other pvr commands worth knowing

Command	What it does
pvr claim -c <challenge> <api>/devices/<id>	Claim an unclaimed device from the CLI.
pvr ps	List the devices you own.
pvr logs <device>	Stream a device's logs.
pvr device scan	Discover Pantavisor devices announcing on the local network.
pvr fastcopy <src> <dst>	Copy state directly between two pvr URLs.

See the Pantavisor documentation for the full pvr reference.