VPM

Overview

vpm (VOLT Package Manager) is a Node CLI for two services: the Registry (package metadata, bundles, search) and the Console (authentication, personal access tokens). CI publishes plugins with it on tag pushes (see plugin-development); run it directly to discover and install plugins.

Installation

npm install -g @voltstack/vpm
vpm --version

Authentication

vpm login

Runs an OAuth-style device-code flow against the Console: requests a code, prints a verification URL and user code, opens the browser (unless --no-browser), then polls until you approve. On success, stores the access/refresh tokens and your profile.

vpm login
vpm login --no-browser   # print the URL/code, don't auto-open

vpm whoami

Resolves the current bearer token against the Console; prints account id, email, and username. Exits non-zero if not logged in.

vpm logout

Revokes the refresh token on the Console and clears stored credentials. --keep-remote clears locally without revoking the server session.

Personal access tokens

PATs are non-interactive credentials for CI. Manage them with vpm token:

vpm token list                                    # alias: ls
vpm token create --label "ci" --scope publish     # prints the token ONCE
vpm token create --label "ci" --expires 2026-01-01T00:00:00Z
vpm token revoke <id>

--scope is repeatable (default read); --scope-mask <n> sets a numeric bitmask; --expires takes an ISO 8601 timestamp. In CI, pass the resulting token to publish/deprecate via --token.

Credential storage

Falls back to the file backend when the keyring is unavailable or VPM_NO_KEYRING=1. Requests use the PAT if present, otherwise the stored access token.

Command reference

Discover

vpm search <query> [--kind workflow|engine|lib] [--page 1] [--page-size 20] [--json]
vpm info <@user/name>            # packument: dist-tags, versions, downloads
vpm info <@user/name@version>    # one version: publish info, size, sha256, platforms

Consume

vpm install <@user/name>[@version|@tag|@range]   # alias: i
vpm install @user/name --platform linux-x86_64 --force
vpm uninstall <@user/name>[@version]             # alias: rm
vpm list                                          # alias: ls — what's in the cache

install resolves the version (see Reference resolution), downloads the bundle for the current platform tag, extracts it into the cache, and makes files under bin/ and scripts/ executable. Workflow plugins also get their manifest cached. --force reinstalls over an existing copy.

Author & publish

vpm init --name @user/name --kind workflow|engine|lib [--version 0.1.0] [--publisher u] [--description d]
vpm pack [dir] [--out file.tgz]
vpm publish [dir] [--bundle <tag>=<path>...] [--bundle-dir ./bundles] [--token <t>] [--dry-run]
vpm deprecate <@user/name@version> "<message>" [--token <t>]

The manifest (vpm.json)

init scaffolds a vpm.json; pack and publish find it by walking up from the target directory. Validated with Zod before any publish.

Publishing flow

vpm publish builds a multipart PUT /packages/:user/:name request:

1. Resolve the manifest and confirm name is @user/name.
2. Collect platform bundles. Pass --bundle <tag>=<path> (repeatable), or let vpm auto-discover *.tgz / *.tar.gz / *.tar.zst files in ./bundles (override with --bundle-dir). A bundle's tag is its filename up to the first dot, so name files after their platform tag, e.g. linux-x86_64.tar.zst.
3. Validate coverage. If the manifest lists platforms, every listed tag must have a bundle; otherwise at least one bundle is required.
4. Attach README.md if present (becomes the rendered package readme).
5. Authenticate with the stored token or --token.
6. Upload — manifest JSON + readme + each bundle blob. --dry-run reports what would be sent and uploads nothing.

Server responses map to errors: 409 version already exists, 403 not authorized for that scope, 422 invalid manifest, 401 bad/missing token.

Building bundles

vpm pack produces a single gzipped tarball of the package directory (vpm.json, README.md, LICENSE, dist, bin by default, or vpm.json + the manifest's files). Use it for inspection and library packages. For native plugins, the per-platform .tar.zst bundles are produced by CoreToolkit's reusable CI workflow and uploaded by publish — see plugin-development.

Reference resolution

Plugin references, with an optional version suffix:

With no version, install uses the latest dist-tag. Resolution order: exact dist-tag → exact semver → semver range (maxSatisfying).

Platform tags

The platform tag is <os>-<arch>, derived from the host (override with --platform):

Common tags: linux-x86_64, darwin-arm64, windows-x86_64.

Cache layout

All state lives under the cache root (VOLT_CACHE_DIR, else ~/.cache/volt):

<cache root>/
  plugins/<publisher>/<name>/<version>/<platform>/   # extracted bundle
  downloads/                                          # downloaded archives
  manifests/<publisher>/<name>.json                   # cached workflow manifests

Archive formats

Downloaded archives are detected by magic bytes (with an extension fallback) and extracted accordingly:

Registry & Console protocol

vpm is a thin client over these HTTP endpoints.