PhyStack CLI

This page documents releases, improvements, and fixes for the @phystack/cli (phy) command-line tool, listed in descending order (newest first).

PhyStack CLI 7.0.0 (Current Release)

Release Date: September 25, 2026 Status: Released

Installation

npm install -g @phystack/cli

Version 7.0 is a ground-up rewrite of the CLI as a single native binary — dramatically faster startup, no Node.js runtime required to execute commands, and a uniform phy <resource> <verb> grammar across the whole platform (apps, installations, devices, spaces, media, analytics, and more). Shell completions (phy completions <shell>) and a man page (phy man) are built in.

Breaking Changes

The command grammar changed. The most important migrations from 6.x:

Scaffolding and registration are now separate, non-interactive commands. phy app create no longer opens an interactive menu. Scaffold with phy app init <name> --type screen|web|edge|cloud (clones the official template for that type; --lang node|python for edge, --lang ts|rust for cloud, --minimal for a dependency-free starter), then register with phy app create <name> --type <type>.
Builds: phy app build and phy app publish are replaced by phy app build create <name> --dir . [--push] [--publish]. --push builds and pushes the container image (edge apps only); --publish publishes the build as soon as it processes. The build version auto-bumps when --version is omitted.
Registry credentials: the interactive Docker credential flow is replaced by phy registry login <registry> — credentials are stored locally (OS keychain) and the image reference is derived from your login.
Device access: the phy dev * family is renamed to phy device * — phy device shell|exec|cp|logs|forward|vnc|screen-devtools|container.
Installation settings: phy app settings is replaced by phy installation settings get|set (with a --space or --device scope, add --resolved for the merged view including overrides).
Simulator: the phy simulator subcommand moved to the standalone phy-simulator binary (npm i -g @phystack/device-simulator). App templates wire it into bun run dev.
Removed: phy vm (VM management) and phy app deploy (dev-mode on-device deploys) are not part of 7.0.
Contexts: kubectl-style configuration via phy config set-context / use-context / get-contexts, with phy tenant set <slug> caching the default tenant per context. For CI, set a personal access token (phy token create) as PHY_TOKEN.

New Features

Web Endpoints: phy web-endpoint manages the public URLs that serve a WEB installation at a Space. list, get, create, update, and delete follow the standard CRUD grammar (phy web-endpoint create --set displayName=... --set installationId=<id> --set spaceId=<id>). phy web-endpoint code <endpoint> mints a session link without a device — the same claim-code URL a QR scan produces, live for the endpoint’s code TTL. Per-endpoint settings overrides reuse the installation settings commands: an endpoint id is a valid --device target for phy installation settings get|set.
Peripheral Descriptors: phy descriptor init <name> scaffolds a descriptor project from the official template (--visibility public|child-tenants|own sets who can see the published descriptor; fixed once created). phy descriptor publish reads the project’s package.json and build output to create the descriptor, or publish a new version if it already exists.

App Types

The supported application types are screen, web, edge, and cloud — cloud apps are scaffoldable from templates for the first time (TypeScript and Rust).

PhyStack CLI 6.2.2

Release Date: June 12, 2026 Status: Released (6.x line)

Installation

npm install -g @phystack/cli@6.2.2

New Features

None

Bug Fixes

phy dev cp Binary Corruption: Copying binary files (coredumps, images, archives) to or from a device could silently corrupt the transferred file while still producing the expected byte count. Transfers are now checksum-verified end to end in both directions: a corrupt, truncated, or interrupted transfer fails with exit code 1 instead of writing a wrong file, and a successful copy prints the byte count, md5, and its verification status, verified against device, or verified by size on devices without an md5 utility.
phy dev cp Uploads of Large Files: Uploading files larger than a few KB to a device no longer fails or corrupts, and no temporary scripts are left behind on the device.
phy dev cp Reliability: Transfers fail fast with a clear error when the remote file is unreadable, the target path is not writable, or the connection drops, and time out after 120 seconds of inactivity instead of hanging forever. Empty files now copy correctly, and progress shows exact byte counts in both directions.

PhyStack CLI 6.2.1

Release Date: June 10, 2026 Status: Released

Installation

npm install -g @phystack/cli@6.2.1

New Features

None

Bug Fixes

phy app publish: Cloud apps published by name (phy app publish <org>.<appName>) are no longer created with the wrong app type.
Stale-Build Warning: No longer fires falsely after publish, and now suggests the correct rebuild command (phy app build).

PhyStack CLI 6.2.0

Release Date: June 3, 2026 Status: Released

Installation

npm install -g @phystack/cli@6.2.0

New Features

Cloud-v2 Installation Lifecycle: phy app build, phy app create, and phy app publish now support the cloud-v2 installation lifecycle.

Bug Fixes

None

PhyStack CLI 6.1.1

Release Date: May 24, 2026 Status: Released

Installation

npm install -g @phystack/cli@6.1.1

New Features

phy dev shell Verbose Mode: Added a -v / --verbose flag that passes -v through to the underlying SSH client for connection debugging.

Bug Fixes

phy login Exit Code: Login failures now exit with code 1 instead of silently continuing, so phy login && phy ... chains in CI no longer proceed past a failed authentication.
Browser Launch Errors: phy login now surfaces browser-launch failures to stderr on headless Linux instead of swallowing them and crashing the login flow.
phy logout Reporting: A corrupt local token file now raises a loud error during logout rather than pretending the refresh token was revoked.
phy dev shell on Windows: The local proxy connection now targets 127.0.0.1 instead of localhost, avoiding a first-attempt WSAECONNREFUSED when Windows resolves localhost to IPv6 first.

PhyStack CLI 6.1.0

Release Date: May 22, 2026 Status: Released

Installation

npm install -g @phystack/cli@6.1.0

New Features

Alpine / musl Support: Two new platform binary packages, @phystack/phy-linux-x64-musl and @phystack/phy-linux-arm64-musl, are now published alongside the existing glibc builds. npm auto-resolves the correct variant on install, so Alpine/musl users get the musl binary and Debian/Ubuntu users get glibc.

Bug Fixes

Diagnostic Install Shim: The CLI shim no longer collapses every spawn failure (ENOENT, EACCES, ENOEXEC, crashes, missing shared libraries) into a silent exit 1. Each failure mode now prints a specific message including the detected runtime (platform, architecture, and libc) and a concrete next step, for example, telling Alpine users to install the musl variant.

PhyStack CLI 6.0.0

Release Date: May 20, 2026 Status: Released

Installation

npm install -g @phystack/cli@6.0.0

Breaking Changes

PHYGRID_* Environment Variables Removed: The CLI now hard-fails at startup with a 1-to-1 rename table if any PHYGRID_* variable is set. There is no deprecation period or silent fallback. Rename every occurrence to its PHYSTACK_* sibling in your shell rc, .env files, CI workflows, and repo secrets. OMBORI_ID_URL is the one intentional carry-over. The full table is in tools/cli/ENVIRONMENT_VARIABLES.md.
phy login No Longer Prompts on Multi-Tenant: When a user belongs to two or more tenants, phy login now prints the available tenants and exits cleanly rather than opening an interactive picker, authentication and tenant selection are now decoupled. Chain phy tenant select <slug> after phy login to select a tenant in scripts. The single-tenant auto-select and zero-tenant warning paths are unchanged (TECH-1117).

New Features

None

Bug Fixes

Simulator --connect: phy simulator start --connect <name> now correctly drives the inner HubDevice instance, opening the socket, running PhyHub authorization, and routing heartbeats through the typed twin-properties helper, so simulators reliably report twin updates to PhyHub. Offline simulator mode is unchanged.