The binary is named blue. Run blue --help for the arguments supported by your installed version.
Typical workflow
In-session controls
Hold Ctrl and press ] while an agent is running. The persistent footer reports Control API connectivity as checking, connected, or offline. Run /agent to choose a new default from the interactive list. The current agent keeps running unless you then select Quit and reload now; otherwise the new default applies the next time Blue starts an agent. Commands that require confirmation show an interactive choice instead of accepting typed arguments. Run /health to check database, blob_storage, package_storage, and inference_proxy; the proxy check appears when the server supplies gateway_inference_proxy_health_url. Run /version to show the installed metaharness version.
Reset a deployment
Use reset when you want to disconnect this workstation from its current Blue deployment and connect to another tenant later. Use blue logout instead when you only need to change the signed-in account without changing deployments.
Reset ends the running agent and removes the active deployment’s Blue-managed overlays and hooks. Your native agent configuration and its backups are not removed.
--yes. From the Ctrl-] control screen, enter /reset to review the action and then /reset yes to confirm it.
When you confirm, Blue:
- Identifies the tenant by its canonical Control API URL and saves its non-secret local state in a tenant-specific archive.
- Retains your preferred agent, local mode preferences, governance cache, applied-state fingerprints, managed package data, merge approvals, MCP staging data, and queued session uploads.
- Removes Blue-owned agent overlays, managed hooks, and package projections. Personal native agent configuration and backup files remain in place.
- Attempts to revoke the OAuth refresh credential, always deletes the local session, and never puts credentials in the archive.
- Removes the active
blue.toml and governance cache so policy from the previous tenant cannot be used by a different tenant.
Blue keeps a separate installation ID for each tenant under ~/.config/blue/identities. Those identities, reconciliation locks, transaction data, and installed PATH shims remain in place. Reconnecting to the same tenant reuses its ID; connecting to another tenant creates a different one.
Connect again
After reset, start Blue normally:
Bare blue and interactive blue <agent> launches detect that no deployment is active and prompt for a Control API URL. If the canonical URL matches a saved tenant, Blue automatically restores that tenant’s non-secret state, refreshes its discovery metadata, starts a new login, and regenerates the removed managed overlays. Queued session uploads remain inactive until their tenant is restored.
Entering a new URL starts with clean tenant state. Running blue setup while another tenant is active performs the same archive-and-detach transition before connecting to the new URL.
Exit behavior
The wrapper attaches the agent to a pseudo-terminal and forwards arguments, input, output, resize events, signals, and the native exit code. Governance or reconciliation failures occur before launch and return a non-zero harness exit status.
Package reconciliation is independent per package. Successful packages activate even if another package fails, and a failed update retains its last usable version when its adapter remains compatible. The command still exits non-zero and the affected harness cannot launch until every required package is active.
Packages modified locally are never silently deleted. Removal unregisters them from the governed overlay and moves modified owned content beneath the metaharness package quarantine for inspection.
Automation
Use blue verify in machine checks. Use blue apply --yes only when the organization has approved noninteractive merges; backups and atomic writes still apply. 