> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluee.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI commands
> Reference the public harness commands and their expected behavior.
The binary is named `blue`. Run `blue --help` for the arguments supported by your installed version.
| Command | Behavior |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `blue` | Set up or renew login when needed, reconcile policy, and launch the preferred eligible agent. Hold Ctrl and press `]` for controls. |
| `blue version` / `blue --version` | Print the installed Blue metaharness version. |
| `blue setup` | Clear the stored session, reconfigure the Control API connection through deployment discovery, and complete login. |
| `blue reset [--yes]` | Disconnect the active deployment, remove Blue-managed agent overlays, and retain non-secret tenant state for a later reconnect. |
| `blue login` | Complete OAuth device authorization and store rotating tokens without writing agent configuration. |
| `blue logout` | Revoke the refresh family when reachable and remove local tokens. |
| `blue doctor` | Show detected harness paths, versions, and policy allow or deny state. |
| `blue agent [NAME]` | Choose the preferred eligible agent used by bare `blue`. |
| `blue status` | Compare desired/applied revisions and report managed-file and package health. |
| `blue verify` | Exit non-zero when policy or managed files are stale. |
| `blue config` | Print the resolved, personalized configuration and its source. |
| `blue apply [--yes]` | Reconcile the configured default agent. |
| `blue daemon [--interval N]` | Keep the default agent current and repair its package drift using TTL polling. |
| `blue gateway` | Provision or reconcile the current user's single managed gateway key. |
| `blue run NAME -- ARGS` | Reconcile and launch one governed native agent, notifying when a newer revision requires a restart. |
| `blue NAME ARGS` | Shorthand for `blue run NAME -- ARGS`. |
| `blue shim install [--dir PATH]` | Install command shims into `~/.local/bin` by default or another directory. |
| `blue shim uninstall [--dir PATH]` | Remove shims previously installed by Blue from the default or specified directory. |
## Typical workflow
```bash theme={null}
blue login
blue doctor
blue agent codex
blue apply
blue verify
blue codex
```
## 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.
| Command | Behavior |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/status` | Show policy and managed-file status. |
| `/health` | Check Control API dependencies. |
| `/version` | Show the Blue metaharness version. |
| `/gateway` | Show gateway account status. |
| `/doctor` | Show detected and eligible agents. |
| `/agent` | Choose the default agent and optionally quit and reload immediately. |
| `/apply` | Review and confirm immediate reconciliation. |
| `/login` | Show identity or interactively confirm reauthentication when the agent must stop. |
| `/logout` | Interactively confirm sign-out. |
| `/reset` | Interactively confirm tenant reset, ending the active agent. |
| `/resume` | Pick an owned or shared portable session, verify it, then gracefully replace the active agent with the native resumed session. Escape or Ctrl-] returns to the active agent. |
| `/help` | Show the available slash commands. |
| `/quit` | Interactively confirm ending the agent and exiting Blue. |
## 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.
From a shell, run:
```bash theme={null}
blue reset
```
The confirmation defaults to No. For automation, pass `--yes`. From the Ctrl-] control screen, enter `/reset` to review the action and then `/reset yes` to confirm it.
When you confirm, Blue:
1. Identifies the tenant by its canonical Control API URL and saves its non-secret local state in a tenant-specific archive.
2. Retains your preferred agent, local mode preferences, governance cache, applied-state fingerprints, managed package data, merge approvals, MCP staging data, and queued session uploads.
3. Removes Blue-owned agent overlays, managed hooks, and package projections. Personal native agent configuration and backup files remain in place.
4. Attempts to revoke the OAuth refresh credential, always deletes the local session, and never puts credentials in the archive.
5. 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:
```bash theme={null}
blue codex
```
Bare `blue` and interactive `blue ` 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.