Matcha CLI · 0.03
Matcha CLI 0.03
Released
More reliable Gemini tool-call continuations through Google AI Studio, plus signed, rollback-safe self-updates for managed macOS Apple Silicon installations.
matcha update --check still only checks. Matcha downloads and installs a release only after you explicitly run matcha update or confirm the update in the TUI.
Google AI Studio Gemini compatibility
- Gemini 3 tool-call continuations now preserve thought signatures as opaque Provider state. After a tool returns, Matcha replays them in the original response-part order. Signatures never appear in the normal UI, logs, diagnostics, snapshots, or error text. Older models and responses without signatures continue to work as before.
- Reasoning settings are now generated by model family: Gemini 3 uses thinkingLevel; Gemini 2.5 Flash continues to use thinkingBudget; and Gemini 2.5 Pro omits the thinking setting when a request disables thinking but the model does not support doing so, leaving Google AI Studio to apply a valid default.
- For unknown or newly introduced Gemini model IDs, Matcha does not guess at reasoning support or send a potentially incompatible thinking setting. Google AI Studio applies the model default instead.
- These changes apply only to the Google AI Studio Gemini generateContent path. Existing endpoints, x-goog-api-key authentication, and Provider-header isolation are unchanged. Other Providers are unaffected.
Self-update experience
- A complete check → confirm → download → verify → atomically activate → restart flow is now available. Once you confirm, Matcha can install and switch to the new version without asking you to run the installer again.
- matcha update --check only checks for and reports an available version. It never downloads or installs anything.
- matcha update shows the target version and asks for confirmation in an interactive terminal. Automation must opt in explicitly with --yes.
- In the TUI, /update checks for a release and asks for a second confirmation before installing the exact channel and version just checked, so the target cannot drift while you decide.
- After installation, Matcha restarts automatically. The update is committed only after the new process passes a health check; if the new version cannot start correctly, Matcha restores the previous version.
- Matcha still does not download on startup or install updates by default. An update begins only when you explicitly start and confirm it.
Download and authenticity checks
- Update requests use only the Matcha self_update_content HTTPS distribution endpoint allowed by the Endpoint Catalog. If it is not configured, Matcha fails closed: it makes no DNS request and never falls back to an xAI or Grok update service.
- Matcha verifies the release source with an Ed25519-signed manifest, then checks the SHA-256 of both the archive and the unpacked matcha binary.
- On macOS Apple Silicon, Matcha also verifies the Apple code signature, the required Team ID, and the Matcha product version reported by the candidate binary.
- Downloads have limits on redirects, response size, and total duration. Available disk space is checked before anything is written.
- The update HTTP client honors Matcha's additional CA trust configuration for controlled enterprise networks.
- Self-installation is initially available only for managed macOS Apple Silicon installations. Ineligible installations receive a clear diagnostic; Matcha does not try to overwrite an unknown path.
Atomic activation and automatic rollback
- A new version is downloaded to a staging directory and does not enter activation until every check has passed.
- Matcha switches versions by creating a new version directory and atomically replacing the current symlink, so users are never exposed to a partially written binary.
- The update journal records preparation, activation, health confirmation, and commit state, making recovery after an interruption deterministic and repeatable.
- The watchdog restores the previous symlink if restart times out, the new process fails to start, health confirmation fails, or monitoring encounters an error.
- Interactive restarts confirm health after the runtime connection is established. Non-interactive --yes updates use a hidden, non-TUI health probe that covers normal process startup, configuration parsing, and runtime initialization.
- Health tokens belong to one update attempt. Expired tokens or leftover environment variables cannot commit a later update, and screen-mode restarts remove the related variables as well.
Upgrading from an older version
Older Matcha builds do not contain the new updater, so they cannot acquire self-update support on their own. Run the official install command one last time. After installing 0.03 or a later compatible version, future updates can be completed inside Matcha.