vpncli client
controls the vpnclid daemon to provide interactive shell, one-shot execution,
file transfer, TCP/UDP tunneling, roaming mosh sessions, and port sharing across
machines without making SSH the product control plane. The 0.2.0 dispatcher
contains 22 operational root commands; vpnclid is the companion daemon,
not a second user command surface.
Published contract: vpncli 0.2.0, OpenCLIs build
2026-08-26-235940. The public registry guide, four-platform CDN metadata,
downloaded archives, and installed macOS, Linux x86-64, and Windows x86-64
payload hashes agree on this release. The macOS payloads are Developer ID
signed, and Apple accepted the notarization submission. The Windows payloads
report Authenticode NotSigned;
that is a signature diagnostic, not a publication gate.
Quick Start
vpncli shell host once or install
the service while logged in so shell hosting starts automatically.
Connect and Control
Direct Remote-to-Remote Copy
vpncli cp A:/absolute/source B:/absolute/destination is a controller-initiated
transfer, not a download followed by an upload. The controller resolves and
pins two distinct exact node IDs, checks fresh presence, active WebRTC sessions,
and the delegated_copy_v1 plus file_transfer_v2 capabilities, then asks A to
open a direct vpncli-file-v2 data channel to B. Payload bytes never pass
through the controller, Cloudflare, relay-data, or a nested exec fallback.
The 0.2.0 boundary is one regular file up to 64 MiB. Both remote paths must be
absolute for their endpoint OS, the destination parent must exist, and
symlink/reparse-point endpoints, directories, devices, FIFOs, and sockets are
rejected. B writes a private stage file, verifies the byte count and SHA-256,
fsyncs, atomically replaces the destination, and persists a receipt. Exit 0 is
reserved for that exact commit receipt.
There is no automatic write retry after delegation. A direct setup failure is
direct_path_unavailable; if receipt observation becomes ambiguous after the
transfer may have progressed, the CLI prints the operation ID and returns
status_unknown.
Retain that ID, claim neither success nor failure, inspect the endpoints, and do
not blindly repeat a potentially committed write.
Set VPNCLI_SHELL_TRANSPORT=relay only for transport diagnosis when you need to
force the relay lane. It is not a performance default.
Node and Presence Management
Presence states have precise meanings:
An online daemon advertises reachability, while shell and share capabilities
come from daemon workers. If
ping fails, inspect service status and daemon
logs on the target before changing client-side aliases.
Port Sharing
Authentication, Daemon, and Service
login, API-key login, and Monolex import accept --force when existing local
auth should be replaced. OTP shapes also support explicit email/device identity
options. logout stops the local daemon before clearing device, pending-login,
node, and inventory state.
Service installation follows the current-user supervisor: the macOS service
backend, a systemd user service on Linux, or a Scheduled Task on Windows. It
points at the stable .openclis/bin/vpnclid path and enables shell-host
autostart only when login state already exists.
Identity and Parser Behavior
The dispatcher scans later argv for
--help/-h before any operational
handler, so vpncli share --help does not publish a share. Other flags are
parsed manually by each handler. A malformed TCP --listen can fall back to
stdio mode; use a validated numeric value in automation.
Security and Transport Boundary
Data-plane commands use DTLS peer-to-peer protection when their WebRTC lane is active. Interactive shell adds P-256 ECDH plus AES-GCM application encryption, so shell bytes remain end-to-end protected on direct-TCP and relay-data fallbacks as well. Registry, presence, share, and auth commands use the HTTPS control plane rather than a WebRTC data channel. The control plane can cache recently validated JWTs; installed clients prefer the dedicatedvpncli-api-key vault entry for node operations when available.
WebRTC success, daemon heartbeat, hosted capability, and command success are
separate proofs. For a deployment smoke, verify service status, status,
resolve, ping, and one real exec or cp operation.
Published Payload Matrix
The archive-extracted payload hashes are independently pinned below.
There is no macOS Intel or Windows ARM64 artifact in this build. Windows 11
Smart App Control or WDAC can reject an unsigned new hash on a particular host
even when its SHA-256 and runtime smokes pass. The 0.2.0 Windows executables
report Authenticode
NotSigned, but this does not make the artifact unavailable
and no longer blocks publication. Keep host execution policy, CDN availability,
installation success, and runtime identity as separate proof layers.
Source tag v0.2.0 points to merge commit
26aeefa0e39cf7acf8999538fbac30b6471aed5f. GitHub-hosted tag jobs did not
start because the account billing gate stopped them before runner assignment;
the native Windows build, macOS signed build, Linux cross-builds, CDN byte
readback, platform installs, code signatures, and real transport smokes are
therefore recorded as separate proof layers rather than described as CI proof.