wt CLI v0.3.0 — 2026-06-15

The first CLI release since v0.2.1 (2026-04-28). Adds the agent install bundle delivery path, the license refresh runtime, and the free-trial MCP affordance. Reshapes wt_subscribe from a per-twin verb to the org billing-plan verb. Hardens the installer’s supply-chain posture and routes every HTTP call through a TLS-floor-enforcing internal client.

What changed

MCP install bundle delivery

Agents can now install commercial twins through wt mcp without leaving the conversation. The wt_install MCP tool calls the platform’s install endpoint and either delivers the twin + license bundle for atomic local commit, queues the request for human approval, or returns a shaped envelope explaining what setup is still required.

License refresh on demand

wt_license_refresh forces a sync of the local license to match the org’s current entitlements. The runtime auto-calls it when a stale-IssuedAt is detected in mcp_metadata; agents can also invoke it directly for manual refresh affordances.

Free-trial surface

wt_trial exposes the one-trial-per-account affordance. Day-Zero users get a signup URL whose post-signup flow activates the trial. Authenticated users get routed to the plan-management page where the web app determines trial eligibility (one trial per account; expired trials require subscribing, not re-trialing).

Supply-chain hardening (installer)

• Strict checksum verification is now the default — set WT_INSTALLER_ALLOW_MISSING_CHECKSUM=1 to opt out (the prior soft-WARN phase is replaced).
• Twin binary download URLs are allowlisted by host and required to be HTTPS.
• The unified HTTP client (internal/httpclient) enforces a TLS 1.2 floor on every call site — 12 call sites migrated.

Runtime durability

• wt-collector mirrors the deleted-wt-auth hardening shape (structured logging, key length floors, bounded request reads, graceful shutdown).
• Shared twin HTTP server gets an explicit ReadHeaderTimeout (closes a slow-loris class for twins running outside wt-admin defaults).
• wt main is wrapped in a deferred panic recovery so an unexpected crash returns a structured exit rather than a raw goroutine dump.

Filesystem hygiene

• ~/.wondertwin/config.json is now enforced as 0600; ~/.wondertwin/ as 0700. Permissions are checked on every load — a permissive config causes wt login to refuse rather than silently trusting it.

Naming cleanup

• API key prefix simplified: wt_live_ → wt_. The redundant live segment served no purpose at customer scale (every key was _live_); shorter prefix reads cleaner and matches the post-billing tier vocabulary.
• Internal: ParseLicenseKey → validateChecksum to stop a parser-without-producer pattern that misled finding F-004.

New commands

• wt verify — CI-time entitlement gate. Reads wondertwin.lock and .wondertwin/project.json, validates every twin against the asserted org’s entitlements via the platform’s entitlements API. Exit 0 on full coverage; exit 1 with a setup URL on a missing entitlement. A GitHub Action wrapper at wondertwin-ai/verify-action@v1 is the recommended customer integration.
• wt replay — surface for replaying recorded scenarios against an installed twin. Companion to existing wt test.

New MCP tools

• wt_install — install a commercial twin into the local runtime via the org’s agent-install policy. Returns the structured envelope (installed / already_installed_refreshed / trial_started_and_installed / queue / deny / upgrade_required / setup_required / policy_error).
• wt_license_refresh — force-refresh the local license to match the server’s current view.
• wt_trial — surface the free-trial affordance. Day-Zero users get a signup URL; authenticated users get routed to plan management for server-side eligibility determination.

All return structured JSON per the MCP envelope contract.

Breaking changes

• wt_subscribe semantics reshaped. Previously a per-twin verb ({twin_name: "stripe"} → subscribe to stripe). Now the org-plan-relationship verb — change the org’s WonderTwin plan (trial → paid; paid → larger plan). The twin_name parameter is removed. Per-twin install moves to wt_install.

  Migration: any MCP client calling wt_subscribe with twin_name should switch to wt_install with the same twin name. The wt_subscribe call site that used {twin_name: "stripe"} now does wt_install({twin_name: "stripe"}). New wt_subscribe callers pass an optional target_plan hint or nothing at all.

  This is the semver-major change driving the version bump from v0.2.x to v0.3.0.

Deprecations

None.

Known limitations

• wt_install against production currently returns SETUP_REQUIRED for all callers because the platform-side install-bundle signing key is not yet populated on production. The envelope shape is correct; the install path is intentionally deferred until the MCP-auth design lands. Customers on the agent install path until that lifts will see “Setup required: complete WonderTwin signup before installing commercial twins.” Community twin install via wt install <twin>@<version> is unaffected.
• wt verify requires the org’s entitlements API to be reachable from the CI runner. For self-hosted CI behind a firewall that can’t reach api.wondertwin.ai, the workaround is the existing wt install lockfile-based reproducible-install — wt verify is the gate, not a replacement for the install path.
• No wt mcp config-change required for existing integrators (Claude Desktop, Cursor, etc.) — the binary is at the same path; new tools auto-appear via tools/list. The breaking change is in tool semantics, not server config.

Dependencies and coordination

• Required to use the new wt mcp install/trial/license-refresh flows: wondertwin-app v0.2.1 or later on the target environment. Calling these against a v0.2.0 platform will succeed at the protocol level but return shaped policy_error envelopes because the corresponding endpoints aren’t deployed.
• Compatible with all existing twin versions in the registry. No twin contract changes in this release.

Install

brew upgrade wondertwin-ai/tap/wt
wt version    # 0.3.0

Fresh install:

brew install wondertwin-ai/tap/wt